iTURBO 

lACCCAA 



REFERENCE 
GUIDE 



ASSEMBLER 






BORLAND 




Reference Guide 



Version 1.0 



Copyright® 1988 
All rights reserved 

Borland International 

1800 Green HiUs Road 

P.O. Box 660001 

Scolts Valley, CA 95066-0001 



This manual was produced with 
Sprint® The Professional Word Processor 



All Borland products are trademarks or registered trademarks of 

Borland International, Inc. Other brand and product names are trademarks 

or registered trademarks of their respective holders. 

Copyright® 1988 Borland International. 

Printed in the U.S.A. 

109876543 



Table of Contents 



Introduction 1 

Hardware and Software Requirements 1 

Whaf s in This Manual 1 

Notational Conventions 2 

How to Contact Borland 3 

Chapter 1 Predefined Symbols 5 

©code 6 

©CodeSize 6 

@Cpu 7 

©curseg 8 

©data 8 

©DataSize 9 

??date 9 

©fardata 9 

©fardata? 10 

©FileName 10 

??filename 10 

??time 10 

??version 11 

©WordSize 11 

Chapter 2 Operators 13 

Arithmetic Precision 13 

Operator Precedence 14 

15 

* 16 

+ (Binary) 16 

+ (Unary) 16 

- (Binary) 17 

- (Unaiy) 18 

18 

/ 19 

: 19 

? 20 

[ ] operator 21 

AND 21 

BYTE 22 

DATAPTR 22 



DUP 23 

DWORD 23 

EQ 24 

FAR 24 

FWORD 25 

GE 25 

GT 26 

HIGH 26 

LARGE 27 

LE 28 

LENGTH 28 

LOW 29 

LT 30 

MASK 30 

MOD 31 

NE 31 

NEAR 32 

NOT 32 

OFFSET 33 

OR 33 

PROG 34 

PTR 34 

PWORD 36 

QWORD 36 

SEG 36 

SHL 37 

SHORT 37 

SHR 38 

SIZE 38 

SMALL 39 

SYMTYPE 40 

TBYTE 40 

THIS 41 

.TYPE 41 

TYPE 42 

UNKNOWN 43 

WIDTH 44 

WORD 45 

XOR 45 

The Special Macro Operators 46 

& 46 

<> 47 

! 48 

% 48 



49 

// ^•' 

Chapters Directives 51 

Sample Directive 52 

186 53 

.286 53 

.286C 53 

.286P 54 

.287 54 

.386 54 

.386C 55 

.386P 55 

.387 55 

.8086 56 

.8087 56 

: 57 

= 58 

ALIGN 58 

•ALPHA 59 

ARG 60 

ASSUME 62 

%BIN 63 

CATSTR 64 

.CODE 64 

CODESEG 65 

COMM 65 

COMMENT 66 

%CONDS 67 

.CONST 67 

CONST 68 

.CREF 68 

%CREF 68 

%CREFALL 69 

%CREFREF 69 

%CREFUREF 70 

%CTLS 70 

.DATA 71 

.DATA? 71 

DATASEG 72 

DB 72 

DD 73 

%DEPTH 74 

DF 75 

DISPLAY 76 

DOSSEG 76 



DP 17 

DQ 17 

DT 78 

DW 79 

ELSE 80 

ELSEIF 80 

EMUL 81 

END 82 

ENDIF 82 

ENDM 83 

ENDP 83 

ENDS 84 

EQU 84 

.ERR 85 

ERR 86 

.ERRl 86 

.ERR2 86 

.ERRB 87 

.ERRDEF 87 

.ERRDIF 88 

.ERRDin 88 

.ERRE 89 

.ERRIDN 89 

.ERRIDNI 90 

ERRIF 91 

ERRIFl 91 

ERRIF2 91 

ERRIFB 91 

ERRIFDEF 91 

ERRIFDIF 92 

ERRIFDin 92 

ERRIFE 92 

ERRIHDN 92 

ERRinDNI 92 

ERRIFNB 93 

ERRIFNDEF 93 

.ERRNB 93 

.ERRNDEF 94 

.ERRNZ 94 

EVEN 94 

EVENDATA 95 

EXITM 96 

EXTRN 96 

.FARDATA 98 



iv 



.FARDATA? 98 

FARDATA 99 

GLOBAL 100 

GROUP 101 

IDEAL 102 

IF 103 

IFl 103 

IF2 104 

IFB 105 

IFDEF 105 

IFDIF, IFDM 106 

IFE 106 

IHDN, IHDNI 107 

IFNB 108 

IFNDEF 108 

%INCL 109 

INCLUDE 109 

INCLUDELIB 110 

INSTR 110 

IRP Ill 

IRPC Ill 

JUMPS 112 

LABEL 113 

.LALL 114 

.LFCOND 114 

%LINUM 114 

%LIST 115 

.LIST 115 

LOCAL 115 

LOCALS 117 

MACRO 119 

%MACS 119 

MASM 120 

MASM51 120 

.MODEL 121 

MODEL 124 

MULTERRS 124 

NAME 125 

%NEWPAGE 125 

%NOCONDS 125 

%NOCREF 126 

%NOCTLS 126 

NOEMUL 127 

%NOINCL 127 



NOJUMPS 128 

%NOLIST 128 

NOLOCALS 128 

%NOMACS 129 

NOMASM51 129 

NOMULTERRS 130 

%NOSYMS 131 

%NOTRUNC 131 

NOWARN 132 

ORG 132 

%OUT 133 

P186 133 

P286 133 

P286N 134 

P286P 134 

P287 134 

P386 134 

P386N 134 

P386P 135 

P387 135 

P8086 135 

P8087 135 

PAGE 135 

%PAGESIZE 136 

%PCNT 137 

PN087 137 

%POPLCTL 138 

PROG 138 

PUBLIC 141 

PURGE 141 

%PUSHLCTL 142 

QUIRKS 142 

.RADIX 143 

RADIX 143 

RECORD 143 

REPT 144 

.SALL 145 

SEGMENT 145 

.SEQ 148 

.SECOND 148 

SIZESTR 148 

.STACK 149 

STACK 149 

STRUG 149 



vi 



SUBSTR 151 

SUBTTL 152 

roSUBTTL 152 

%SYMS 153 

%TABSIZE 153 

%TEXT 154 

.TFCOND 154 

TITLE 154 

%TITLE 155 

%TRUNC 155 

UDATASEG 156 

UFARDATA 156 

UNION 156 

USES 158 

WARN 159 

.XALL 160 

.XCREF 160 

.XLIST 160 

Appendix A Turbo Assembler Syntax Summary 161 

Lexical Grammar 161 

valid_line 161 

white_space 161 

space_char 162 

id_string 162 

id_stmg2 162 

id_char 162 

id_chr2 162 

number_striiig 162 

num_string 162 

digits 162 

digit 162 

alphanums 163 

alpha 163 

exp 163 

str_string 163 

punctuation 163 

MASM Mode Expression Grammar 164 

mexprl 164 

mexpr2 164 

mexpr3 164 

mexpr4 164 

mexpr5 164 

mexpr6 165 

mexprZ 165 



VII 



inexprS 165 

mexpr9 165 

mexprlO 165 

inexprll 166 

mexprl2 166 

mexprl3 166 

Ideal Mode Expression Grammar 166 

pointer 166 

type 166 

pointer2 167 

pointers 167 

expr 167 

expr2 167 

exprS 167 

expr4 168 

expr5 168 

expr6 168 

expr7 168 

expr8 168 

expr9 168 

exprlO 169 

Appendix B Compatibility Issues 171 

Environment Variables 172 

Microsoft Binary Floating-Point Format 172 

Turbo Assembler Quirks Mode 172 

Byte Move to/from Segment Register 173 

Erroneous Near Jump to Far Label or Procedure 173 

Loss of Type Information with = and EQU Directive 173 

Segment-Alignment Checking 174 

Signed Immediate Arithmetic and Logical Instructions 174 

Masm 5.1 Features 174 

Masm 5.1 /Quirks Mode Features 175 

Appendix C Turbo Assembler Highlights 177 

Extended Command-Line Syntax 177 

GLOBAL Directive 177 

Local Symbols 178 

Conditional Jump Extension 178 

Ideal Mode 178 

UNION Directive/STRUC Nesting 178 

EMUL and NOEMUL Directives 179 

Explicit Segment Overrides 179 

Constant Segments 179 

Extended LOOP Instruction in 386 Mode 179 



viii 



Extended Listing Controls 180 

Alternate Directives 180 

Predefined Variables 180 

Masm 5.0 and 5.1 Enhancements 180 

Improved SHL and SHRHandling 181 

Appendix D Turbo Assembler Utilities 183 

The Stand-Alone MAKE Utility 183 

A Quick Example 184 

Creating a Makefile 185 

Using a Makefile 186 

Stepping Through 187 

Creating Makefiles 188 

Components of a Makefile 188 

Comments 189 

Explicit Rules 189 

Special Considerations 190 

Implicit Rules 191 

Special Considerations 193 

Examples 194 

Command Lists 194 

Prefix 194 

Command Body 195 

Examples 195 

Macros 196 

Defining Macros 197 

Using Macros 197 

Special Considerations 198 

Predefined Macros 198 

Directives 200 

File-Inclusion Directive 201 

Conditional Directives 201 

Error Directive 204 

Undef Directive 204 

Using MAKE 204 

Command-Line Syntax 204 

A Note About Stopping MAKE 205 

The BUILTINS.MAK File 205 

How MAKE Searches for Makefiles 206 

The TOUCH Utility 206 

MAKE Command-Line Options 206 

MAKE Error Messages 207 

Fatals 207 

Errors 208 

Turbo Link 210 



IX 



Invoking TLINK 210 

Using Response Files 211 

TLINK Options 213 

The /x, /m, /s Options 213 

The /I Option 214 

The /i Option 214 

The /n Option 214 

The /c Option 214 

The /d OpHon 215 

The /e Option 215 

The /t Option 216 

The /v Option 216 

The /3 Option 216 

Restrictions 216 

Error Messages 217 

Fatal Errors 217 

Nonfatal Errors 219 

Warnings 220 

TUB: The Turbo Librarian 220 

The Advantages of Using Object Module Libraries 221 

The Components of a TLIB Command Line 221 

The Operation List 222 

File and Module Names 223 

TLIB Operations 223 

Creating a Library 224 

Using Response Files 224 

Advanced Operation: The /C Option 225 

Examples 226 

Creating an Extended Dictionary: The /E Option 226 

GREP: A File-Search Utility 227 

The GREP Options 227 

Order of Precedence 229 

The Search String 229 

Operators in Regular Expressions 229 

The File Specification 230 

Examples with Notes 231 

OBJXREF: The Object Module Cross-Reference Utility 234 

The OBJXREF Command Line 234 

Command-Line Options 235 

Conti-ol Options 235 

Report Options 235 

Response Files 236 

Freeform Response Files 236 

Linker Response Files 237 



The /D Command 237 

The /O Command 237 

The /N Command 238 

Sample OBJXREF Reports 238 

Report by Public Names (/RP) 239 

Report by Module (/RM) 240 

Report by Reference (/RR) (Default) 240 

Report by External References (/RX) 240 

Report of Module Sizes (/RS) 241 

Report by Class Type (/RC) 241 

Report of Unreferenced Symbol Names (/RU) 242 

Verbose Reporting (/RV) 242 

Examples Using OBJXREF 243 

OBJXREF Error Messages and Warnings 243 

Error Messages 243 

Warnings 244 

TCREF: The Source Module Cross-Reference Utility 244 

Response Files 245 

CompaHbility with TLINK 245 

Switches 245 

Output 246 

The Global (or Linker-Scope) Report 246 

The Local (or Module-Scope) Report 246 

Appendix E Error Messages 249 

Information Messages 249 

Warning and Error Messages 250 

Fatal Error Messages 272 

Index 275 



xi 



List of Tables 



Table 2.1: MASM Mode Operator Precedence 14 

Table 2.2: Ideal Mode Operator Precedence 15 

Table 3.1: Default Segments and Types for Tiny Memory Model 122 

Table 3.2: Default Segments and Types for Small Memory Model 123 

Table 3.3: Default Segments and Types for Medium Memory Model 123 

Table 3.4: Default Segments and Types for Compact Memory Model . . . 123 
Table 3.5: Default Segments and Types for Large or Huge Memory 

Model 123 

Table 3.6: Default Segments and Types for Turbo Pascal (TPASCAL) 

Memory Model 124 



xii 



o 



This book is the second of the two books accompanying the Turbo 
Assembler package. Now that you've probably thoroughly perused the first 
manual {User's Guide) in this set, you'll want to look at this one for all the 
nitty-gritty information. 

The Reference Guide is just that — a straight and to-the-point reference about 
Turbo Assembler. If you find you still need to know more about the basics 
of assembly language, go back to the User's Guide for some in-depth 
discussions. 



Hardware and Software Requirements 

Turbo Assembler runs on the IBM PC family of computers, including the 
XT, AT, and PS/2, along with all true compatibles. Turbo Assembler 
requires MS-DOS 2.0 or later and at least 256K of memory. 

Turbo Assembler generates instructions for the 8086, 80186, 80286, and 
80386 processors. It also generates floating-point instructions for the 8087, 
80287, and 80387 numeric coprocessors. 



What's in This Manual 

Here's what we discuss in this manual: 

Chapter 1: Predefined Symbols tells you about Turbo Assembler's equates. 

Chapter 2: Operators describes the various operators Turbo Assembler 
provides. 

Chapter 3: Directives provides, in alphabetical order, detailed information 
about all the Turbo Assembler directives. 

Appendix A: Turbo Assembler Syntax illustrates Turbo Assembler expres- 
sions (both MASM and Ideal modes) in modified Backus-Naur form (BNF). 
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Appendix B: Compatibility Issues covers the differences between MASM 
and Turbo Assembler MASM mode. 

Appendix C: Turbo Assembler Highlights details Turbo Assembler's 
enhancements that add to those of MASM. 

Appendix D: Turbo Assembler Utilities describes six utilities that come 
with this package: MAKE, TLINK, TLIB, GREP, OBJXREF, and TCREF. 

Appendix E: Turbo Assembler Error Messages describes all the error 
messages that can be generated when using Turbo Assembler: information 
messages, fatal error messages, warning messages, and error messages. 



Notational Conventions 

When we talk about IBM PCs or compatibles, we're referring to any- 
computer that uses the 8088, 8086, 80186, 80286, and 80386 chips (all of 
these chips are commonly referred to as 80x86). When discussing PC-DOS, 
DOS, or MS-DOS, we're referring to version 2.0 or greater of the operating 
system. 

All typefaces were produced by Borland's Sprint: The Professional Word 
Processor, output on a PostScript printer. The different typefaces displayed 
are used for the following pinposes: 

Italics In text, italics represent labels, placeholders, variables, and 

arrays. In syntax expressions, placeholders are set in itaUcs 
to indicate that they are user-defined. 

Boldface Boldface is used in text for directives, instructions, symbols, 

and operators, as weU as for command-line options. 

CAPITALS In text, capital letters are used to represent instructions, 
directives, registers, and operators. 

Monospace Monospace type is used to display any sample code, text or 

code that appears on your screen, and any text that you 
must actually type to assemble, link, and run a program. 

Keycaps In text, keycaps are used to indicate a key on your keyboard. 

It is often used when describing a key you must press to 
perform a particular function; for example, "Press Enter after 
typing your program name at the prompt." 
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How to Contact Borland 



If, after reading this manual and using Turbo Assembler, you would like to 
contact Borland with comments, questions, or suggestions, we suggest the 
following procedures: 

□ The best way is to log on to Borland's forum on CompuServe: Type GO 
BPROGB at the main CompuServe menu and follow the menus to Turbo 
Assembler. Leave your questions or comments here for the support staff 
to process. 

□ If you prefer, write a letter detailing your problem and send it to 

Technical Support Department 

Borland International 
P.O. Box 660001 

1800 Green Hills Drive 
Scotts Valley, CA 95066 U.S.A. 

dYou can also telephone our Technical Support department at (408) 
438-5300. To help us handle your problem as quickly as possible, have 
these items handy before you call: 

o product name and version number 
e product serial number 
• computer make and model number 
o operating system and version number 

If you're not familiar with Borland's No-Nonsense License statement, 
now's the time to read the agreement at the front of this manual and mail in 
your completed product registration card. 
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Predefined Symbols 



Turbo Assembler provides a number of predefined symbols that you can 
use in your programs. These symbols can have different values at different 
places in your source file. They are similar to equated symbols that you 
define using the EQU directive. When Turbo Assembler encounters one of 
these symbols in your source file, it replaces it with the current value of that 
predefined symbol. 

Some of these symbols are text (string) equates, some are numeric equates, 
and others are aliases. The string values can be used anywhere that you 
would use a character string, for example to initialize a series of data bytes 
using the DB directive: 

NOW DB ??time 

Numeric predefined values can be used anywhere that you would use a 
number: 

IF ??version GT lOOh 

Alias values make the predefined symbol into a synonym for the value it 
represents, allowing you to use the predefined symbol name anywhere you 
would use an ordinary symbol name: 

ASSUME cs:@code 

All the predefined symbols can be used in both MASM and Ideal mode. 

If you use the /ml command-line option when assembling, you must use 
the predefined symbol names exactly as they are described on the following 
pages. 
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The followmg rule applies to predefined symbols starting with an at-sign 
(@): The first letter of each word that makes up part of the symbol name is an 
uppercase letter (except for segment names); the rest of the word is lowercase. As 
an example. 



SCodeSize 
SFileName 
eWordSize 



The exception is redefined symbols, which refer to segments. Segment 
names begin with an at-sign (@) and are all lowercase. For example. 



@curseg 
@fardata 



For symbols that start with two question marks (??), the letters are all 
lowercase. For example. 



??data 
??version 



^code 



Function 
Remarks 



Example 



Alias equate for .CODE segment name 

When you use the simplified segmentation directives 
(.MODEL, and so on), this equate lets you use the name 
of the code segment in expressions, such as ASSUMEs 
and segment overrides. 

.CODE 

mov ax,@code 

mov dx,ax 

ASSUME ds:@code 



©CodeSize 



Function 
Remarks 



Numeric equate that indicates code memory model 

©CodeSize is set to for the small and compact memory 
models that use near code pointers, and is set to 1 for all 
other models that use far code pointers. 

You can use this symbol to control how pointers to 
functions are assembled, based on the memory model. 
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Example 



IF eCodeSize EQ 
procptr DW PROCl 

ELSE 
procptr DD PROCl 

ENDIF 



/•pointer to near procedure 
/•pointer to far procedure 



^Cpu 



Function 
Remarks 



Numeric equate that returns information about current 
processor 

The value returned by @Cpu encodes the processor type 
in a number of single-bit fields: 

Bit Description 



10 
11 



8086 instructions enabled 
80186 instructions enabled 

80286 instructions enabled 

80386 instructions enabled 
Privileged instructions enabled 

(80286 and 80386) 

8087 numeric processor instructions 

80287 numeric processor instructions 

80387 numeric processor instructions 



The bits not defined here are reserved for future use. 
Mask them off when using @Cpu so that your programs 
will remain compatible with future versions of Turbo 
Assembler. 

Since the 8086 processor family is upward compatible, 
when you enable a processor type with a directive like 
.286, the lower processor types (8086, 80186) are auto- 
matically enabled as well. 

Note: This equate only provides information about the 
processor you've selected at assembly-time via the .286 
and related directives. The processor type your program 
is executing on at run time is not indicated. 
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Example 



I PUSH = eCpu AND 2 
IF IPUSH 
PUSH 1234 
ELSE 

mov ax, 1234 

push ax 
ENDIF 



; allow immediate push on 186 and above 



©curseg 



Function 
Remarks 



Example 



Alias equate for current segment 

©curseg changes throughout assembly to reflect the 
current segment name. You usually use this after you 
have used the simplified segmentation directives 
(.MODEL, and so on). 

Use ©curseg to generate ASSUME statements, segment 
overrides, or any other statement that needs to use the 
current segment name. 

.CODE 

ASSUME cs:@curseg 



@data 



Function 
Remarks 



Example 



Alias equate for near data group name 

When you use the simplified segmentation directives 
(.MODEL, and so on), this equate lets you use the group 
name shared by all the near data segments (.DATA, 
.CONST, .STACK) in expressions such as ASSUMES 
and segment overrides. 

.CODE 

mov ax,@data 
mov ds,ax 
ASSUME ds:@data 
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©DataSize 



Function 
Remarks 



Example 



Numeric equate that indicates the data memory model 

@DataSize is set to for the tiny, small, and medium 
memory models that use near data pointers, set to 1 for 
the compact and large models that use far data pointers, 
and set to 2 for the huge memory model. 

You can use this symbol to control how pointers to data 
are assembled, based on the memory model. 

IF @DataSize EQ 1 

lea si,VarPtr 

mov al, [BYTE PTR si] 
ELSE 

les si/VarPtr 

mov al, [BYTE PTR es:si] 
ENDIF 



??date 



Function 
Remarks 

See Also 
Example 



String equate for today's date 

??date defines a text equate that represents today's date. 
The exact format of the date string is determined by the 
DOS country code. 

??time 

asradate DB ??date ; 8-byte string 



©fardata 



Function 
Remarks 



Example 



Alias equate for initialized far data segment name 

When you use the simplified segmentation directives 
(.MODEL, and so on), this equate lets you use the name 
of the initialized far data segment (.FARDATA) in 
expressions such as ASSUMES and segment overrides. 

mov ax,@fardata 

mov ds,ax 

ASSUME ds:@fardata 
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©fardata? 

Function 
Remarks 



Example 



Alias equate for uninitialized far data segment name 

When you use the simplified segmentation directives 
(.MODEL, and so on), this equate lets you use the name 
of the uninitialized far data segment (.FARDATA?) in 
expressions such as ASSUMES and segment overrides. 

mov ax,@fardata? 

mov ds,ax 

ASSUME ds:@fardata? 



©FileName 



Function 
See Also 



Alias equate for current assembly file 
??filename 



??filename 



Function 
Remarks 

Example 



String equate for current assembly file 

??filename defines an eight-character string that repre- 
sents the file name being assembled. If the file name is 
less than eight characters, it is padded with spaces. 

SrcName DB ??filename ; 8-bytes always 



??time 



Function 
Remarks 

See Also 
Example 



String equate for the current time 

??time defines a text equate that represents the current 
time. The exact format of the time string is determined 
by the DOS country code. 

??date 

asmtime DB ??time ; 8-byte string 
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??version 

Function 
Remarks 



Example 



Numeric equate for this Turbo Assembler version 

The high byte is the major version number, and the low 
byte is the minor version number. For example, V2.1 
would be represented as 201h. 

??version lets you write source files that can take 
advantage of features in particular versions of Turbo 
Assembler. 

This equate also lets your source files know whether 
they are being assembled by MASM or Turbo Assem- 
bler, since ??version is not defined by MASM. 

IFDEF ??version 

; Turbo Assembler stuff 

ENDIF 



iWordSize 



Function 
Remarks 

Example 



Numeric equate that indicates 16- or 32-bit segments 

©WordSize returns 2 if the current segment is a 16-bit 
segment, or 4 if the segment is a 32-bit segment. 

IF eWordSize EQ 4 

mov esp, OlOOh 
ELSE 

mov sp,0100h 
ENDIF 
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Operators 



Operators let you form complex expressions that can be used as an operand 
to an instruction or a directive. Operators act upon operands, such as 
program sjrmbol names and constant values. Turbo Assembler evaluates 
expressions when it assembles your source file and uses the calculated 
result in place of the expression. One v^ay you can use expressions is to 
calculate a value that depends on other values that may change as you 
modify your source file. 

This chapter details the operators Turbo Assembler provides. 

Arithmetic Precision 

Turbo Assembler uses 16- or 32-bit arithmetic, depending on whether you 
have enabled the 80386 processor with the .386 or .386P directive. When 
you are assembling code for the 80386 processor or in Ideal mode, some 
expressions will yield different results than when they are evaluted in 16- 
bit mode; for example, 

DW (lOOOh * lOOOh) / lOOOh 

generates a word of lOOOh in 32-bit mode and a word of in 16-bit mode. In 
16-bit mode, multiplication results in an overflow condition, saving only 
the bottom 16 bits of the result. 
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Operator Precedence 



Turbo Assembler evaluates expressions using the following rules: 

■ Operators with higher precedence are performed before ones with lower 
precedence. 

■ Operators with the same precedence are performed starting with the 
leftmost one in the expression. 

■ If an expression contains a subexpression within parentheses, that 
subexpression is evaluated first because expressions within parentheses 
have the highest priority. 

Ideal mode and MASM mode have a different precedence for some 
operators. The following two tables show the precedence of the operators 
in both modes. The first line in each table shows the operators with the 
highest priority, and the last line those operators with the lowest priority. 
Within a line, all the operators have the same priority. 

Table 2.1: MASM Mode Operator Precedence 
<>, 0, [], LENGTH, MASK, SIZE, WIDTH 
. (structure member selector) 
HIGH, LOW 
+, - (unary) 
: (segment override) 
OFFSET, PTR, SEG, THIS, TYPE 
*, /, MOD, SHL, SHR 
+, - (binary) 

EQ, GE, GT, LE, LT, NE 
NOT 
AND 
OR, XOR 
LARGE, SHORT, SMALL, .TYPE 
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Table 2.2: Ideal Mode Operator Precedence 

0, D, LENGTH, MASK, OFFSET, SEG, SIZE, WIDTH 

HIGH, LOW 

+, - (unary) 

*, /, MOD, SHL, SHR 

+, - (binary) 

EQ, GE, GT, LE, LT, NE 

NOT 

AND 

OR, XOR 

: (segment override) 

. (structure member selector) 

HIGH (before pointer), LARGE, LOW (before pointer), 
PTR, SHORT, SMALL, SYMTYPE 

The operators allowed in expressions follow in alphabetical order. 







Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Marks an expression for early evaluation 
MASM, Ideal 

{expression) 

Use parentheses to alter the normal priority of operator 
evaluation. Any expression enclosed within parentheses 
will be evaluated before the operator(s) that comes 
before or after the parentheses. 

+, -, *, /, MOD, SHL, SHR 

(3+4) * 5 /evaluates to 35 
3+4*5 /evaluates to 23 
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Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Multiplies two integer expressions 
MASM, Ideal 

expressionl * expression2 

expressionl and expressionl must both evaluate to integer 
constants. The * operator can also be used between a 
register and a constant to support 386 addressing 
modes. 

+, -, I, MOD, SHL, SHR 

SCREENSIZE = 25 * 80 ;} chars onscreen 

The * operator can also be used between a register and a 
constant to support 386 addressing modes. 



+ (Binary) 



Function 
Mode 
Syntax 
Remarks 

See also 
Example 



Adds two expressions 
MASM, Ideal 

expressionl + expression2 

At least one of expressionl or expressionl must evaluate to 
a constant. One expression can evaluate to an address. 

-, *, I, MOD, SHL, SHR 

X DW 4 DUP (?) 

XPTR DW X + 4 ; third word in buffer 



+ (Unary) 



Function 
Mode 
Syntax 
Remarks 



Indicates a positive number 
MASM, Ideal 

+ expression 

This operator has no effect. It is available merely to 
make expKcit positive constants. 
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See also 
Example 



- *, /, MOD, SHL, SHR 

Foo DB +4 ; redundant + 



(Binary) 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Subtracts two expressions 
MASM, Ideal 

expressionl - expression! 

There are three combinations of operands you can use 
with subtraction: 

m expressionl and expressionl can both evaluate to 
integer constants. 

a expressionl and expressionl can both be addresses as 
long as both addresses are within the same segment. 
When you subtract two addresses, the result is a con- 
stant. Ideal mode checks expressionl and expressionl 
for consistency much more stringently than MASM 
mode. In particular. Ideal mode correctly handles 
subtracting a segment from a far pointer, leaving just 
an offset fixup in cases where this is a valid operation. 

■ expressionl can be an address and expressionl can be a 
constant, but not vice versa. The result is another 
address. 

+, *, /, MOD, SHL, SHR 



DATA SEGMENT 










DW 


1 






XYZ 


EQU 


10 






VALl 


DW 


XYZ 


- 1 


; constant 9 


VAL2 


DW 


2 






VISIZE 


DW 


VAL2 


- VALl 


/constant 2 


VIBEFORE 


DW 


VALl 


- 2 


/points to DW before VALIE 


DATA 


ENDS 
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- (Unary) 

Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Changes the sign of an expression 
MASM, Ideal 

- expression 

expression must evaluate to a constant. If expression is 
positive, the result will be a negative number of the 
same magnitude. If expression is negative, the result will 
be a positive number. 

+,*,/, MOD, SHL,SHR 

LOWTEMP DB -10 ;pretty chilly 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Selects a structure member 
MASM, Ideal 

memptr. fieldname 

In MASM mode, memptr can be any operand that refers 
to a memory location, and fieldname can be the name of 
any member in any structure or even a constant expres- 
sion. If memptr is the name of a structure (like XINST), 
there is still no requirement that fieldname be a member 
in that structure. This operator acts much like the + 
operator: It adds the offset within the structure of field- 
name to the memory address of memptr, but it also gives 
it the size of field name. 

In Ideal mode, its operation is much stricter, memptr 
must evaluate to a pointer to a structure, and fieldname 
must be a member of that structure. This lets you have 
different structures with the same field names, but a 
different offset and size. If you want to use a base and/ 
or index register for memptr, you must precede it with a 
typecast for the name of the structure you want to access 
(take a look at the example that follows). 

STRUC 

X STRUC 
MEMBERl DB ? 
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MEMBER2 DW ? 

X ENDS 

XINST X <> 

;an instance of STRUC X 
;MASM mode 

mov [bx] .Member2,l 
/•Ideal mode 

mov [(X PTR bx).Member2],l 



/notice typecast 



/ 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Divides two integer expressions 
MASM, Ideal 

expressionl I expression2 

expression! and expressionl must both evaluate to integer 
constants. The result is expressionl is divided by 
expressionl; any remainder is discarded. You can get the 
remainder by using the MOD operator with the same 
operands you supplied to the / operator. 

+, -, », MOD, SHL, SHR 

X = 55 / 10 ;= 5 (integer divide) 



Function 
Mode 
Syntax 
Remarks 



Generates segment or group override 
MASM, Ideal 

segorgroup : expression 

The colon (:) forces the address of expression to be 
generated relative to the specified segment or group. 
You use this to force the assembler to use something 
other than its default method for accessing expression. 

You can specify segorgroup in several ways: 

D as a segment register: CS, DS, ES, or SS (or FS or GS if 
you have enabled the 80386 processor with the P386 
or P386N directive) 

■ as a segment name defined with the SEGMENT 
directive 
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Example 



■ as a group name defined with the GROUP directive 

■ as an expression starting with the SEG operator 

expression can be a constant- or a memory-referencing 
expression. 



mov cl,es: [si+4] 
VarPtr DD DGROUP:MEMVAR 



Function 
Mode 
Syntax 
Remarks 



Initializes with indeterminate data 
MASM, Ideal 

Dx ? 

Dx refers to one of the data allocation directives (DB, 
DD, and so on). Use ? when you want to allocate data 
but don't want to explicitly assign a value to it. 

You should use ? when the data area is initialized by 
your program before being used. Using ? rather than 
makes the initialization method explicit and visible in 
your source code. 

When you use ? as the only value in or outside a DUP 
expression, no object code is generated. If you use ? 
inside a DUP expression that also contains initialized 
values, it will be treated as a 0. 

Using ? outside of a DUP causes the program counter to 
be advanced but no data to be emitted. You can also use 
? for the same purpose in, for example, a structure: 





X struc 




/•declare structure 




a db 1 








X ends 








xinst ? 




/undefined structu: 


See also 


DUP 






Example 


MyBuf DB 20 


DUP 


(?) /allocate un( 
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[ ] operator 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Specifies addition or indexed memory operand 
MASM, Ideal 

[expressionl] [expression2] 

This operator behaves very differently in MASM mode 
and in Ideal mode. 

In MASM mode, it can act as an addition operator, 
simply adding expressionl to expression!. The same 
limitations on operand combinations apply; for example, 
expressionl and expressionl can't both be addresses. [ ] 
can also indicate register indirect memory operands, 
using the BX, BP, SI, and DI registers. The indirect 
regis ter(s) must be enclosed within the [ ]. An indirect 
displacement may appear either inside or outside the 
brackets. 

In Ideal mode, [ ] means "memory reference." Any 
operand that addresses memory must be enclosed in 
brackets. This provides a clear, predictable, unam- 
biguous way of controlling whether an operand is 
immediate or memory-referencing. 



MASM mode 

mov al,BYTE PTR es:[bx] 

mov al,cs:10h 
Ideal mode 

mov al,[BYTE es:bx] 

mov al, [cs:10h] 



AND 



Function 
Mode 
Syntax 
Remarks 



Bitwise logical AND 
MASM, Ideal 

expressionl AND expression2 

Performs a bit-by-bit logical AND of each bit in 
expressionl and expressionl. The result has a 1 in any bit 
position that had a 1 in both expressions and a in all 
other bit positions. 
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See also 
Example 



NOT, OR, XOR 

mov al, 11110000b AND lOlOOOOOB ; loads lOlOOOOOB 



BYTE 



Function 
Mode 
Syntax 
Remarks 



Forces expression to be byte size 
Ideal 

BYTE expression 

expression must be an address. The result is an expres- 
sion that points to the same memory address but always 
has BYTE size, regardless of the original size of 
expression. 

You usually use this operator to define the size of a 
forward-referenced expression, or to explicitly state the 
size of a register indirect expression from which the size 
cannot be determined. 

In MASM mode, you must use the PTR directive 
preceded with the BYTE type to perform this function. 



See also 


PTR 


Example 


mov [BYTE bx],l ;byte immediate move 
mov [BYTE X],l /forward reference 
X DB 


DATAPTR 


Function 


Forces expression to model-dependent size 


Mode 


Ideal 


Syntax 


DATAPTR expression 


Remarks 


Declares expression to be a near or far pointer, 
depending on selected memory model. 


See also 


PTR, UNKNOWN 


Example 


mov [DATAPTR bx],l 
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DUP 



Function 
Mode 
Syntax 
Remarks 



Example 



Repeats a data allocation 
MASM, Ideal 

count DUP [expression [, expression] .. .) 

count defines the number of times that the data defined 
by the expressionis) will be repeated. The DUP operator 
appears after one of the data allocation directives (DB, 
DW, and so on). 

Each expression is an initializing value that is valid for 
the particular data allocation type that DUP follows. 

You can use the DUP operator again within an expres- 
sion, nested up to 17 levels. 

You must always surround the expression values with 
parentheses, (). 

WRDBUF DW 40 DUP (1) ;40 words initialized to 1 
SQUARE DB 4 DUP (4 DUP (0)) ;4x4 array of 



DWORD 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Forces expression to be doubleword size 
Ideal 

DWORD expression 

expression must be an address. The result is an expres- 
sion that points to the same memory address but always 
has DWORD size, regardless of the original expression 
size. 

You usually use this operator to define the size of a 
forward-referenced expression. 

To perform this function in MASM mode, you must use 
the PTR directive preceded by the DWORD type. 

PTR 

call DWORD FPTR 
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EQ 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Returns true if expressions are equal 
MASM, Ideal 

expressionl EQ expression2 

expression! and expressionl must both evaluate to con- 
stants. EQ returns true (-1) if both expressions are equal 
and returns false (0) if they have different values. 

EQ considers expressionl and expressionl to be signed 
32-bit numbers, with the top bit being the sign bit. This 
means that -1 EQ OFFFFFFFFh evaluates to true. 



NE, LT, LE, GT, GE 



ALIE = 4 EQ 3 
ATRUTH = 6 EQ 6 



;= (false) 
;= 1 (true) 



FAR 



Function 
Mode 
Syntax 
Remarks 



Forces an expression to be a far code pointer 
Ideal 

FAR expression 

expression must be an address. The result is an expres- 
sion that points to the same memory address but is a far 
pointer with both a segment and an offset, regardless of 
the original expression type. 

You usually use this operator to call or jump to a 
forward-referenced label that is declared as FAR later in 
the source file. 

To perform this function in MASM mode, you must use 
the PTR directive preceded by the FAR type. 



See also 


NEAR 




Example 


call FAR ABC 
ABC PROC FAR 


/•forward reference 
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FWORD 

Function 
Mode 
Syntax 
Remarks 



Forces expression to be 32-bit far pointer size 
Ideal 

FWORD expression 

expression must be an address. The result is an expres- 
sion that points to the same memory address but always 
has FWORD size, regardless of the original expression 
size. 

You usually use this operator to define the size of a 
forward-referenced expression or to explicitly state the 
size of a register indirect expression from which the size 
cannot be determined. 

To perform this function in MASM mode, you must use 
the PTR directive preceded by the FWORD type. 



See also 


PTR, PWORD 




Example 


.386 






call FWORD [bx] 


;far indirect 48-bit call 




jmp FWORD funcp 


; forward reference 




funcp DF myproc 


; indirect pointer to PROC 



GE 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Returns true if one expression is greater than another 
MASM, Ideal 

expressionl GE expression2 

expression! and expressionl must both evaluate to con- 
stants. GE returns true (-1) if expressionl is greater than 
or equal to expressionl and returns false (0) if it is less. 

GE considers expressionl and expressionl to be signed 
33-bit numbers, with the top bit being the sign bit. This 
means that 1 GE -1 evaluates to true, but 1 GE 
OFFFFFFFFh evaluates to false. 

EQ, GT, LE, LT, NE 

TROOTH = 5 GE 5 
AFIB = 5 GE 6 
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GT 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Returns true if one expression is greater than another 
MASM, Ideal 

expressionl GT expression2 

expression! and expressionl must both evaluate to con- 
stants. GT returns true (-1) if expressionl is greater than 
expressionl, and returns false (0) if it is less than or equal. 

GT considers expressionl and expressionl to be signed 
33-bit numbers, with the top bit being the sign bit. This 
means that 1 GT -1 evaluates to true, but 1 GT 
OFFFFFFFFh evaluates to false. 

EQ, GE, LE, LT, NE 

AFACT = 10 GT 9 
NOTSO = 10 GT 11 



HIGH 



Function 

Mode 

Syntax 

Remarks 



See also 



Returns the high part of an expression 
MASM, Ideal 

HIGH expression 

Ideal mode only: 

type HIGH expression 

HIGH returns the top 8 bits of expression, which must 
evaluate to a constant. 

In Ideal nnode, HIGH in conjimction with LOW becomes 
a powerful mechanism for extracting arbitrary fields 
from data items, type specifies the size of the field to 
extract from expression and can be any of the usual size 
specifiers (BYTE, WORD, DWORD, and so on). You can 
apply more than one HIGH or LOW operator to an 
expression; for example, the following is a byte address 
pointing to the third byte of the doubleword DBLVAL: 

BYTE LOW WORD HIGH DBLVAL 

LOW 
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Example 



;MASM and Ideal modes 

magic EQU 1234h 

mov cl,HIGH magic 

Ideal 

/•Ideal mode only 

big DD 12345678h 

mov ax, {WORD HIGH big] 



; loads 1234h into AX 



LARGE 



Function 
Mode 
Syntax 
Remarks 



Sets an expression's offset size to 32 bits 
MASM, Ideal (386 modes only) 

LARGE expression 

expression is any expression or operand, which LARGE 
converts into a 32-bit offset. You usually use this to 
remove ambiguity about the size of an operation. For 
example, if you have enabled the 80386 processor with 
the P386 directive, this code can be interpreted as either 
a far call with a segment and 16-bit offset or a near call 
using a 32-bit offset: 

jmp [DWORD PTR ABC] 

You can remove the ambiguity by using the LARGE 
directive: 

jmp LARGE [DWORD PTR ABC] ; 32-bit offset near call 

In this example, LARGE appears outside the brackets, 
thereby affecting the interpretation of the DWORD read 
from memory. If LARGE appears inside the brackets, it 
determines the size of the address from which to read 
the operand, not the size of the operand once it is read 
from memory. For example, this code means XYZ is a 
4-byte pointer: 

jmp LARGE [LARGE DWORD PTR XYZ] 

Treat it as a 32-bit offset, and JMP indirect through that 
address, reading a JMP target address that is also a 
32-bit offset. 

By combining the LARGE and SMALL operators, both 
inside and outside brackets, you can effect any combi- 
nation of an indirect JMP or CALL from a 16- or 32-bit 
segment to a 16- or 32-bit segment. 
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See also 
Example 



You can also use LARGE to avoid erroneous assump- 
tions when accessing forward-referenced variables: 

mov ax, [LARGE FOOBAR] ;FOOBAR is in a USE32 segment 

LARGE and SMALL can be used with other ambiguous 
instructions, such as LIDT and LGDT. 

SMALL 

;MASM and Ideal modes 
magic EQU 1234h 
mov bl, HIGH magic 
Ideal 



/•Ideal mode only 
big DD 12345678h 
mov ax, [word HIGH big] 



/leads 1234h into AX 



LE 



Function 

Mode 

Syntax 

Remarks 



See also 
Example 



Returns true if one expression is less than or equal to 
another 

MASM, Ideal 

expression! LE expression! 

expression! and expression! must both evaluate to con- 
stants. LE returns true (-1) if expression! is less than or 
equal to expression! and returns false (0) if it is greater. 

LE considers expression! and expression! to be signed 33- 
bit numbers, with the top bit being the sign bit. This 
means that 1 LE -1 evaluates to false, but 1 LE 
OFFFFFFFFh evaluates to true. 

EQ, GE, GT, LT, NE 

YUP = 5 LT 6 ;true = -1 



LENGTH 



Function 

Mode 

Syntax 



Returns number of allocated data elements 
MASM, Ideal 

LENGTH name 
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Remarks 



See also 
Example 



name is a symbol that refers to a data item allocated with 
one of the data allocation directives (DB, DD, and so 
on). LENGTH returns the number of repeated elements 
in name. If name was not declared using the DUP 
operator, it always returns 1. 

LENGTH returns 1 even when name refers to a data item 
that you allocated with multiple items (by separating 
them with commas). 

SIZE, TYPE 

MSG DB "Hello" 

array DW 10 DUP (0) 

numbrs DD 1,2,3,4 

var DQ ? 

Imsg = LENGTH MSG ;= 1, no DUP 

larray = LENGTH ARRAY ;=10, DUP repeat count 

Inumbrs = LENGTH NUMBRS ;= 1, no DUP 

Ivar = LENGTH VAR ;= 1, no DUP 



LOW 



Function 

Mode 

Syntax 

Remarks 



See also 



Returns the low part of an expression 
MASM, Ideal 

LOW expression 

Ideal mode only: 

type LOW expression 

LOW returns the bottom 8 bits of expression, which 
must evaluate to a constant. 

In Ideal mode, LOW in conjunction with HIGH becomes 
a powerful mechanism for extracting arbitrary fields 
from data items, type specifies the size of the field to 
extract from expression and can be any of the usual size 
specifiers (BYTE, WORD, DWORD, and so on). You can 
apply more than one LOW or HIGH operator to an 
expression; for example, 

BYTE LOW WORD HIGH DBLVAL 

is a byte address pointing to the third byte of the 
doubleword DBLVAL. 

HIGH 
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Example 



;MASM and Ideal modes 

magic EQU 1234h 

mov bl,LOW magic 

ideal 

/Ideal mode only 

big DD 12345678h 

mov ax, [WORD LOW big] 



: loads 5678h into AX 



LT 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Returns true if one expression is less than another 
MASM, Ideal 

expressionl LT expression2 

expression! and expressionl must both evaluate to con- 
stants. LT returns true (-1) if expressionl is less than 
expressionl and returns false (0) if it is greater than or 
equal. 

LT considers expressionl and expressionl to be signed 33- 
bit numbers, with the top bit being the sign bit. This 
means that 1 LT -1 evaluates to false, but 1 LT 
OFFFFFFFFH evaluates to true. 

EQ, GE, GT, LE, NE 

JA = 3 LT 4 ;true = -1 



MASK 



Function 

Mode 

Syntax 

Remarks 



Returns a bit mask for a record field 
MASM, Ideal 

MASK recordfieldname 
MASK record 

recordfieldname is the name of any field name in a pre- 
viously defined record. MASK returns a value with bits 
turned on to correspond to the position in the record 
that recordfieldname occupies. 

record is the name of a previously defined record. MASK 
returns a value with bits turned on for all the fields in 
the record. 
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You can use MASK to isolate an individual field in a 
record by ANDing the mask value with the entire 
record. 



See also 


WIDTH 




Example 


STAT RECORD A:3,b:4, 
NEWSTAT STAT <0,2,1> 


,c:5 




mov al, NEWSTAT 


;get record 




and al,MASK B 


/isolate B 




mov a 1, MASK STAT 


;get mask for entire record 



MOD 


Function 


Returns remainder (modulus) from dividing two ex- 
pressions 


Mode 


MASM, Ideal 


Syntax 


expressions! MOD expression2 


Remarks 


expression! and expression! must both evaluate to integer 
constants. The result is the remainder of expression! 
divided by expression!. 


See also 


+,-,*,/,SHL,SHR 


Example 


REMAINS =17/5 ;= 2 


NE 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Returns true if expressions are not equal 
MASM, Ideal 

expression! NE express ion2 

expression! and expression! must both evaluate to con- 
stants. NE returns true (-1) if both expressions are not 
equal and returns false (0) if they are equal. 

NE considers expression! and expression! to be signed 
32-bit numbers, with the top bit being the sign bit. This 
means that -1 NE OFFFFFFFFh evaluates to true. 

EQ, GE, GT, LE, LT 

aint = 10 NE 10 ; false = 
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NEAR 

Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Forces an expression to be a near code pointer 
Ideal 

NEAR expression 

expression must be an address. The restilt is an expres- 
sion that points to the same memory address but is a 
NEAR pointer with only an offset and no segment, 
regardless of the original expression type. 

You usually use this operator to call or jump to a far 
label or procedure with a near jump or call instruction. 
See the example section for a typical scenario. 

To perform this function in MASM mode, you must use 
the PTR directive preceded with the NEAR type. 

FAR 

Ideal 

PROG farp FAR 

;body of procedure 
ENDP farp 

; still in same segment 
push cs 
call NEAR PTR farp /faster/smaller than far call 



NOT 



Function 


Bitwise complement 


Mode 


MASM, Ideal 


Syntax 


NOT expression 


Remarks 


NOT inverts all the 




1 and 1 bits into 0. 


See also 


AND, OR, XOR 


Example 


mov al,NOT 11110011b 



;loads 00001100b 
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OFFSET 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Returns an offset within a segment 
MASM, Ideal 

OFFSET expression 

expression can be any expression or operand that 
references a memory location. OFFSET returns a con- 
stant that represents the number of bytes between the 
start of the segment and the referenced memory 
location. 

If you are using the simplified segmentation directives 
(MODEL, and so on) or Ideal mode, OFFSET 
automatically returns offsets from the start of the group 
that a segment belongs to. If you are using the normal 
segmentation directives, and you want an offset from 
the start of a group rather than a segment, you must 
explicitly state the group as part of expression. For 
example, 

mov si, OFFSET BUFFER 

is not the same as 

mov si, OFFSET DGROUP: BUFFER 

unless the segment that contains BUFFER happens to be 
the first segment in DGROUP. 

SEG 

.DATA 

msg DB "Starting analysis" 

.CODE 

mov si, OFFSET msg /address of MSG 



OR 



Function 
Mode 
Syntax 
Remarks 



Bitwise logical OR 
MASM, Ideal 

expression! OR expression2 

OR performs a bit-by-bit logical OR of each bit in 
expressionl and expression!. The result has a 1 in any bit 
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See also 
Example 



position that had a 1 in either or both expressions, and a 
in all other bit positions. 

AND, NOT, XOR 

mov al, 11110000b OR 10101010b ;loads 11111010b 



PROC 



Function 
Mode 
Syntax 
Remarks 



Forces an expression to be a near or far code pointer 
Ideal 

PROC expression 

expression must be an address. The result is an expres- 
sion that points to the same memory address but is a 
near or far pointer, regardless of the original expression 
type. If you specified the TINY, SMALL, or COMPACT 
memory model with the .MODEL directive, the pointer 
will be near. Otherwise, it will be a far pointer. 

You usually use PROC to call or jump to a forward- 
referenced function when you are using the simplified 
segmentation directives. The example section shows a 
typical scenario. 

To perform this function in MASM mode, you must use 
the PTR directive preceded with the PROC type. 



See also 


NEAR, FAR 


Example 


.MODEL large 




.CODE 




Ideal 




call PROC Testl 




PROC Testl 



/•actually far due to large model 



PTR 



Function 
Mode 
Syntax 
Remarks 



Forces expression to have a particular size 
MASM, Ideal 

type PTR expression 

expression must be an address. The result of this 
operation is a reference to the same address, but with a 
different size, as determined by type. 
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Typically, this operator is used to explicitly state the size 
of an expression whose size is undetermined, but 
required. This can occur if an expression is forward 
referenced, for example. 

type must be one of the following in Ideal mode: 

■ UNKNOWN, BYTE, WORD, DWORD, FWORD, 
PWORD, QWORD, TBYTE, DATAPTR, or the name 
of a structure, for data 

■ SHORT, NEAR, FAR, PROC for code 

In Ideal mode, you don't need to use the PTR operator. 
You can simply follow the type directly with expression. 

In MASM mode, type can be any of the following 
numbers: 

bO = UNKNOWN, 1 = BYTE, 2 = WORD, 4 = 
DWORD, 6 = PWORD, 8 = QWORD, 10 = TBYTE for 

data 

B OFFFFh = NEAR, OFFFEh = FAR for code 

Correspondingly, in MASM mode the following key- 
words are recognized as having these values: 

B UNKNOWN = 0, BYTE = 1, WORD = 2, DWORD = 
4, PWORD = 6, FWORD = 6, QWORD = 8, TBYTE = 
10, DATAPTR = 2 or 4 (depending on MODEL in use) 
for data 

B NEAR = OFFFFh, FAR = OFFFEh, PROC = OFFFFh or 
OFFFEh (depending on MODEL in use) for code 

See also BYTE, WORD, DWORD, QWORD, FWORD, PWORD, 

TBYTE, NEAR, FAR, PROC, DATAPTR 

Example mov byte PTR[SI],10 ;byte immediate mode 

fid QWORD PTR val ;load quadword float 

val DQ 1234.5678 
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PWORD 



Function 
Mode 
See also 



Forces expression to be 32-bit, far pointer size 

MASM, Ideal 

FWORD 



QWORD 



Function 
Mode 
Syntax 
Remarks 



Forces expression to be quadword size 
Ideal 

QWORD expression 

expression must be an address. The result is an expres- 
sion that points to the same memory address but always 
has QWORD size, regardless of the original size of 
expression. 

You usually use QWORD to define the size of a 
forward-referenced expression, or to explicitly state the 
size of a register indirect expression from which the size 
cannot be determined. 

To perform this function in MASM mode, you must use 
the PTR directive preceded by the QWORD type. 



See also 


PTR 




Example 


fadd [QWORD BX] 


;sizeless indirect 




fsubp [QWORD X] 


; forward reference 




.DATA 






X DQ 1.234 





SEG 



Function 
Mode 
Syntax 
Remarks 



Returns the segment address of an expression 
MASM, Ideal 

SEG expression 

expression can be any expression or operand that 
references a memory location. SEG returns a constant 
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that represents the segment portion of the address of the 
referenced memory location. 



See also 


OFFSET 




Example 


.DATA 

temp DW 

.CODE 

mov ax,SEG temp 






mov ds,ax 


;set up segment register 




ASSUME ds:SEG temp 


;tell assembler about it 



SHL 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Shifts the value of an expression to the left 
MASM, Ideal 

expression SHL count 

expression and count must evaluate to constants. SHL 
performs a logical shift to the left of the bits in expression. 
Bits shifted in from the right contain 0, and the bits 
shifted off the left are lost. 

A negative count causes the data to be shifted the 
opposite way. 

SHR 

mov al, 00000011b SHL 3 ; loads OOOllOOOB 



SHORT 



Function 
Mode 
Syntax 
Remarks 



Forces an expression to be a short code pointer. 
MASM, Ideal 

SHORT expression 

expression references a location in your current code 
segment. SHORT informs the assembler that expression 
is within -128 to +127 bytes from the current code 
location, which lets the assembler generate a shorter 
JMP instruction. 

You only need to use SHORT on forward-referenced 
JMP instructions, since Turbo Assembler automatically 
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See also 
Example 



generates the short jumps if it already knows how far 
away expression is. 

NEAR, FAR 



jmp SHORT done /generate small jump instruction 
;less than 128 bytes of code here 



Done; 



SHR 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Shifts the value of an expression to the right 
MASM, Ideal 

expression SHR count 

expression and count must evaluate to constants. SHR 
performs a logical shift to the right of the bits in 
expression. Bits shifted in from the left contain 0, and the 
bits shifted off the right are lost. 

A negative count causes the data to be shifted the 
opposite way. 

SHL 

mov al,80h SHR 2 ; loads 20h 



SIZE 



Function 
Mode 
Syntax 
Remarks 



See also 



Returns size of allocated data item 
MASM, Ideal 

SIZE name 

name is a symbol that refers to a data item allocated with 
one of the data allocation directives (DB, DD, and so 
on). In MASM mode, SIZE returns the value of 
LENGTH name multiplied by TYPE name. Therefore, it 
does not take into account multiple data items, nor does 
it account for nested DUP operators. 

In Ideal mode, SIZE returns the byte count within a 
DUP. To get the byte count of DUP, use LENGTH. 

LENGTH, TYPE 
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Example 



msg DB 
array DW 
numbrs DD 
var DQ ? 
;MASM mode 
smsg = SIZE msg 
sarray = SIZE array 
snumbrs = SIZE numbrs 
svar = SIZE var 
/Ideal mode 
smsg = SIZE msg 
sarray = SIZE array 
snumbrs = SIZE numbrs 
svar = SIZE var 



"Hello" 

10 DUP(4 DUP (1), 0) 

1,2,3,4 



1, string has length 1 
= 20, 10 DUPS of DW 
4, length = 1, DD = 4 bytes 
= 8, 1 element, DQ = 8 bytes 

1, string has length 1 
= 20, 10 DUPS of DW 
4, length = 1, DD = 4 bytes 
=8, 1 element, DQ = 8 bytes 



SMALL 



Function 
Mode 
Syntax 
Remarks 



Sets an expression's offset size to 16 bits 
MASM, Ideal (386 code generation only) 

small expression 

expression is any expression or operand. SMALL 
converts it into a 16-bit offset. You usually use this to 
remove ambiguity about the size of an operation. For 
example, if you have enabled the 80386 processor with 
the P386 directive, 

jmp [DWORD PTR ABC] 

can be interpreted as either a far call with a segment and 
16-bit offset or a near call using a 32-bit offset. You can 
remove the ambiguity by using the SMALL directive: 

jmp small [DWORD PTR ABC] ;16-bit offset far call 

In this example, SMALL appears outside the brackets, 
thereby affecting the interpretation of the DWORD read 
from memory. If SMALL appears inside the brackets, it 
determines the size of the address from which to read 
the operand, not the size of the operand once it is read 
from memory. For example, 

CODE SEGMENT USE32 

jmp small [small DWORD PTR XYZ] 

means XYZ is a 4-byte pointer thaf s treated as a 16-bit 
offset and segment, and JMP indirect through that 
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See also 



address, reading a near JMP target address that is also a 
16-bit offset. 

By combining the LARGE and SMALL operators, both 
inside and outside brackets, you can effect any combi- 
nation of an indirect JMP or CALL from a 16- or 32-bit 
segment to a 16- or 32-bit segment. LARGE and SMALL 
can also be used with other ambiguous instructions, 
such as LIDT and LGDT. 

LARGE 



SYMTYPE 



Function 
Mode 
Syntax 
Remarks 

See also 



Returns a byte describing a symbol 
Ideal 

SYMTYPE <expression> 

SYMTYPE functions very similarly to .TYPE, with one 
minor difference: If expression contains an undefined 
symbol, SYMTYPE returns an error, unlike .TYPE. 

.TYPE 



TBYTE 



Function 
Mode 
Syntax 
Remarks 



See also 



Forces expression to be 10-byte size 
Ideal 

TBYTE expression 

expression must be an address. The result is an expres- 
sion that points to the same memory address but always 
has TBYTE size, regardless of the original size of 
expression. 

You usually use TBYTE to define the size of a forward- 
referenced expression, or to explicitly state the size of a 
register indirect expression from which the size cannot 
be determined. 

To perform this function in MASM mode, you must use 
the PTR directive preceded by the TBYTE type. 

PTR 
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Example 



fid [TBYTE bx] 
fst [TBYTE X] 
X DT 



;sizeless indirect 
/forward reference 



THIS 



Function 

Mode 

Syntax 

Remarks 



Example 



Creates an operand whose address is the current seg- 
ment and location counter 

MASM, Ideal 

THIS type 

type describes the size of the operand and whether it 
refers to code or data. It can be one of the following: 

■ NEAR, FAR, or PROC (PROC is the same as either 
NEAR or FAR, depending on the memory set using 
the MODEL directive) 

■ BYTE, WORD, DATAPTR, DWORD, FWORD, 
PWORD, QWORD, TBYTE, or a structure name 

You usually use this operator to build EQU and = 
statements. 

ptrl EQU THIS WORD ;same as following statement 
ptr2 LABEL WORD 



.TYPE 



Function 
Mode 
Syntax 
Remarks 



Returns a byte describing a symbol 
MASM 



.TYPE name 



name is a symbol that may or may not be defined in the 
source file. .TYPE returns a byte that describes the sym- 
bol with the following fields: 
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See also 
Example 



Bit Description 

Program relative symbol 

1 Data relative symbol 

2 Constant 

3 Direct addressing mode 

4 Is a register 

5 Symbol is defined 
7 Symbol is external 

If bits 2 and 3 are both zero, the expression uses register 
indirection (like [BX], and so on). 

If .TYPE returns zero, the expression contained an 
undefined symbol. 

.TYPE is usually used in macros to determine how to 
process different kinds of arguments. 



SYMTYPE 

IF (.TYPE ABC) AND 3 
ASSUME ds:SEG abc 
mov ax,SEG abc 
mov ds,ax 
ENDIF 



;is it segment-relative? 



TYPE 



Function 
Mode 
Syntax 
Remarks 



Returns a number indicating the size or type of symbol 
MASM, Ideal 

TYPE expression 

TYPE returns one of the following values, based on the 
type of expression: 
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See also 
Example 



BYTE 1 

WORD 2 

DWORD 4 

FWORD 6 

PWORD 6 

QWORD 8 

TBYTE 10 

NEAR OFFFFHh 

FAR OFFFEh 

constant 

structure } of bytes in structure 

LENGTH, SIZE 

bvar DB 1 

darray DD 10 DUP (1) 

X STRUC 

DW ? 

DT ? 
X ENDS 

fp EQU THIS FAR 
tbvar = TYPE bvar ;= 1 
tdarray = TYPE darray ;= 4 
tx = TYPE X ;=12 

tfp = TYPE fp ; OFFFEh 



UNKNOWN 



Function 
Mode 
Syntax 
Remarks 



Removes type information from an expression 
Ideal 

UNKNOWN expression 

expression is an address. The result is the same expres- 
sion, but with its type (BYTE, WORD, and so on) 
removed. 

Use UNKNOWN to force yourself to explicitly mention 
a size whenever you want to reference a location. This is 
useful if you want to treat the location as a type of 
union, allowing the storage of many different data 
types. Incorrectly then, if you define another name 
without an explicit size to reference the location, the 
assembler can't use the original data allocation size. 

You can also use an address with UNKNOWN size 
much like you would use register indirect memory- 
referencing for one operand, and pin down the size of 
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See also 
Example 



the operation by using a register for the other operand. 
By defining a name as UNKNOWN, you can use it 
exactly as you would an anonymous register expression 
such as [BX]. 

To perform this function in MASM mode, you must use 
the PTR directive preceded by the BYTE type. 



See also 


PTR 




Example 


.DATA 






workbuf DT 


;can hold up to a DT 




workptr EQU UNKNOWN WORKBUF 


; anonymous pointer 




.CODE 






/EXAMPLE 1 






mov [BYTE PTR WORKPTR],! 


; store a byte 




fstp [QWORD PTR WORKPTR] 


/•store a qword 




mov [WORKPTR],! 


; error — no type 




/EXAMPLE 2 






mov al, [WORKPTR] 


;no complaint 




mov ax, [WORKPTR] 


;no complaint either! 


WIDTH 


Function 


Returns the width in bits of 


a field in a record 


Mode 


MASM, Ideal 




Syntax 


WIDTH recordfieldname 
WIDTH record 




Remarks 


recordfieldname is the name of any field name in a 



previously defined record. WIDTH returns a value of 
the number of bits in the record that recordfieldname 
occupies. 

record is the name of a previously defined record. 
WIDTH returns a value of the total number of bits for 
all the fields in the record. 

IVIASK 

/Macro determines maximum value for a field 

maxval MACRO FIELDNAME 

value=2 

REPT WIDTH FIELDNAME - ! 
value = value * 2; 

ENDM 
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value = value - 1 
ENDM 



WORD 



Function 
Mode 
Syntax 
Remarks 



Forces expression to be word size 
Ideal 

WORD expression 

expression must be an address. The result is an expres- 
sion that points to the same memory address but always 
has WORD size, regardless of the original size of 
expression. 

You usually use WORD to define the size of a forward- 
referenced expression, or to expHcitly state the size of a 
register indirect expression from which the size cannot 
be determined. 

To perform this function in MASM mode, you must use 
the PTR directive preceded with the WORD type. 



See also 


PTR 




Example 


mov [WORD bx],l 


;word immediate move 




mov [WORD X] , 1 


/forward reference 




X DW 





XOR 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Bitwise logical exclusive OR 
MASM, Ideal 

expressionl XOR expression2 

XOR performs a bit-by-bit logical exclusive OR of each 
bit in expressionl and expressionl. The result has a 1 in 
any bit position that had a 1 in one expression but not in 
the other, and a in all other bit positions. 

AND, NOT, OR 

mov al, 11110000b XOR 11000011b ;AL = 00110011b 
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The Special Macro Operators 



You use the special macro operators when calling macros and within macro 
and repeat-block definitions. You can also use them with the arguments to 
conditional assembly directives. 

Here's a brief summary of the special macro operators: 

& Substitute operator 



<> 



% 



Literal text string operator 
Quoted character operator 
Expression evaluate operator 
Suppressed comment 



The operators let you modify symbol names and individual characters so 
that you can either remove special meaning from a character or determine 
when an argument gets evaluated. 



& 



Function 
Mode 
Syntax 
Remarks 



Example 



Substitute operator 
MASM, Ideal 

sna/ne 

name is the value of the actual parameter in the macro 
invocation or repeat block. In many situations, param- 
eter substitution is automatic, and you don't have to use 
this operator. You must use this operator when you wish 
substitution to take place inside a quoted character 
string, or when you want to "paste" together a symbol 
from one or more parameters and some fixed characters. 
In this case, the & prevents the characters from being 
interpreted as a single name. 

MMEMSG MACRO StrDef,NUM 
MSG & NUM DB 'SStrDef 
ENDM 

If you call this macro with 

MAKEMSG 9,<Enter a value: > 
it will expand to 

MSG9 DB 'Enter a value: ' 
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<> 

Function 
Mode 
Syntax 
Remarks 



Example 



Literal text string operator 
MASM, Ideal 

<text> 

text is treated as a single macro or repeat parameter, 
even if it contains commas, spaces, or tabs that usually 
separate each parameter. Use this operator when you 
want to pass an argument that contains any of these 
separator characters. 

You can also use this operator to force Turbo Assembler 
to treat a character literally, without giving it any special 
meaning. For example, it you wanted to pass a semi- 
colon (;) as a parameter to a macro invocation, you 
would have to enclose it in angle brackets (<;>) to 
prevent it from being treated as the start of a comment. 

Turbo Assembler removes the outside set of angle 
brackets each time a parameter is passed during the 
invocation of a macro. To pass a parameter down 
through several levels of macro expansion, you must 
supply one set of angle brackets for each level. 

MANYDB MACRO VALS 
IRP X,<VALS> 

ENDM 

ENDM 

When calling this macro, you must enclose multiple 
values in angle brackets so they get treated as the single 
parameter VALS: 

MANYDB <4,6,0,8> 

The IRP repeat directive still has angle brackets around 
the parameter name because the set of brackets around 
the parameter are stripped when the macro is called. 
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• 

Function 
Mode 
Syntax 
Remarks 



Example 



Quoted character operator 
MASM, Ideal 

! character 

The ! operator lets you call macros with arguments that 
contain special macro operator characters. This is some- 
what equivalent to enclosing the character in angle 
brackets. For example, !& is the same as <&>. 

MAKEMSG MACRO StrDef,NUM 
MSG & NUM DB 'SStrDef 
ENDM 

MAKEMSG <Can't enter !> 99> 

In this example, the argument would have been pre- 
maturely terminated if the ! operator had not been used. 



% 



Function 
Mode 
Syntax 
Remarks 



Expression evaluate operator 
MASM, Ideal 

^expression 

expression can be either a numeric expression using any 
of the operands and operators described in this chapter 
or it can be a text equate. If it is a numeric expression, 
the string that is passed as a parameter to the macro 
invocation is the result of evaluating the expression. If 
expression is a text equate, the string passed is the text of 
the text equate. The evaluated expression will be 
represented as a nunnerical string in the current RADIX. 

Use this operator when you want to pass the string 
representing a calculated result, rather than the expres- 
sion itself, to a macro. Also, a text macro name can be 
specified after the %, causing a full substitution of the 
text macro body for the macro argument. 
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Example 



DEFSYM MACRO NUM 
???SNUM: 
ENDM 

DEFSYM %5+4 

results in the following code label definition: 

1119: 



// 



Function 
Mode 
Syntax 
Remarks 



Example 



Suppressed comment 
MASM, Ideal 

; ; text 

Turbo Assembler ignores all text following the double 
semicolon (;;). Normal comments are stored as part of 
the macro definition and appear in the listing any time 
the macro is expanded. Comments that start with a 
double semicolon (;;) are not stored as part of the macro 
definition. This saves memory, particularly if you have a 
lot of macros that contain a lot of comments. 

SETBYTES MACRO VarName,val 

VarName DB 10 DUP (val) ;;this comment doesn't get saved 

ENDM 
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Directives 



A source statement can either be an instruction or a directive. An instruction 
source line generates object code for the processor operation specified by the 
instruction mnemonic and its operands. A directive source line tells the 
assembler to do something unrelated to instruction generation, including 
defining and allocating data and data structures, defining macros, speci- 
fying the format of the listing file, controlling conditional assembly, and 
selecting the processor type and instruction set. 

Some directives define a symbol whose name you supply as part of the 
source line. These include, for example, SEGMENT, LABEL, and GROUP. 
Others change the behavior of the assembler but do not result in a S3nTibol 
being defined, for example, ORG, IF, %LIST. 

The directives presented here appear in alphabetical order (excluding 
punctuation); for example, .CODE appears just before CODESEG. 

The reserved keywords %TOC and %NOTOC do not perform any 
operation in the current version of Turbo Assembler. Future versions will 
use these keywords, so you should avoid using them as symbols in your 
programs. 

The directives fall into three categories: 

1. The MASM-style directives: Turbo Assembler supports all MASM-style 
directives. When you use Turbo Assembler in Ideal mode, the syntax of 
some of these directives changes. For these directives, the description 
notes the syntax for both modes. 

2. The new Turbo Assembler directives: These directives provide added 
functionality beyond that provided by MASM. 
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3. Turbo Assembler directives that are synonyms for existing MASM 
directives: These synonyms provide a more organized alternative to 
some existing MASM directives. For example, rather than .LIST and 
.XLIST, you use %LIST and %NOLIST. As a rule, all paired directives 
that enable and disable an option have the form xxxx and NOxxxx. The 
synonyms also avoid using a period (.) as the first character of the 
directive name. The MASM directives that start with a period are not 
available in Turbo Assembler's Ideal mode, so you must use the new 
synonyms instead. 

All Turbo Assembler directives that control the listing file start with the 
percent (%) character. 

In the syntax section of each entry, the following typographical conventions 
are used: 

■ Brackets ([ ]) indicate optional arguments (you do not need to type in the 
brackets). 

H Ellipses (...) indicate that the previous item nnay be repeated as many 
times as desired. 

■ Items in italics are placeholders that you replace with actual symbols and 
expressions in your program. 



Sample Directive 



Function 

Mode 

Syntax 

Remarks 
See also 
Example 



Brief description of what the directive does. 

What mode(s) the directive operates in. 

How the directive is used; italicized items are user- 
defined 

General information about the directive. 

Other related directives. 

Sample code using the directive. 
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.186 



Function 
Mode 
Syntax 
Remarks 

See also 

Example 



Enables assembly of 80186 instructions 
MASM 

.186 

186 enables assembly of the additional instructions sup- 
ported by the 80186 processor. (Same as P186.) 

.8086, .286, .286C, .286P, .386, .386C, .386P, P8086, P286, 
P286N, P286P, P386, P386N, P386P 

.186 

push 1 ;valid instruction on 186* 



.286 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Enables assembly of non-privileged 80286 instructions 
MASM 

.286 

.286 enables assembly of the additional instructions 
supported by the 80286 processor in non-privileged 
mode. It also enables the 80287 numeric processor 
instructions exactly as if the .287 or P287 directive had 
been issued. (Same as P286N and .286C.) 

.8086, .186, .286C, .286P, .386, .386C, .386P, P8086, P286, 
P286N, P286P, P386, P386N, P386P 



.286 
fstsw ax 



;only allowed with 80287 



.286C 



Function 
See also 



Enables assembly of non-privileged 80286 instructions 

.8086, .186, .286, .286P, .386, .386C, .386P, P8086, P286, 
P286N, P286P, P386, P386N, P386P 
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,286P 



Function 
Mode 
Syntax 
Remarks 



See also 



Enables assembly of all 80286 instructions 
MASM 

.286P 

.286P enables assembly of all the additional instructions 
supported by the 80286 processor, including the 
privileged mode instructions. It also enables the 80287 
numeric processor instructions exactly as if the .287 or 
P287 directive had been issued. (Same as P286P.) 

.8086, .186, .286, .286C, .386, .386C, .386P, P8086, P286, 
P286N, P286P, P386, P386N, P386P 



.287 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Enables assembly of 80287 coprocessor instructions 
MASM 

.287 

.287 enables assembly of all the 80287 numeric coproces- 
sor instructions. Use this directive if you know you'll 
never run programs using an 8087 coprocessor. This 
directive causes floating-point instructions to be 
optimized in a manner incompatible with the 8087, so 
don't use it if you want your programs to run using an 
8087. (Same as P287.) 

.8087, .387, P8087, PN087, P287, P387 



.287 

fsetpm 



;only on 287 



.386 



Function 

Mode 

Syntax 



Enables assembly of non-privileged 80386 instructions 
MASM 

.386 
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Remarks 



See also 
Example 



.386 enables assembly of the additional instructions sup- 
ported by the 80386 processor in non-privileged mode. It 
also enables the 80387 numeric processor instructions 
exactly as if the .387 or P387 directive had been issued. 
(Same as P386N and .386C.) 

.8086, .186, .286C, .286, .286P, .386C, .386P, P8086, P286, 
P286N, P286P, P386, P386N, P386P 



.386 
stosd 



;only valid as 386 instruction 



.386C 



Function 
See also 



Enables assembly of 80386 instructions 

.8086, .186, .286C, .286, .286P, .386, .386P, P8086, P286, 
P286N, P286P, P386, P386N, P386P 



.386P 



Function 
Mode 
Syntax 
Remarks 



See also 



Enables assembly of all 80386 instructions 
MASM 

.386P 

.386P enables assembly of all the additional instructions 
supported by the 80386 processor, including the 
privileged mode instructions. It also enables the 80387 
numeric processor instructions exactly as if the .387 or 
P387 directive had been issued, (Same as P386P.) 

.8086, .186, .286C, .286, .286N, .286P, .386, .386C, P8086, 
P286, P286N, P286P, P386, P386N, P386P 



.387 



Function 
Mode 
Syntax 
Remarks 



Enables assembly of 80387 coprocessor instructions 
MASM 



.387 



.387 enables assembly of all the 80387 numeric coproces- 
sor instructions. Use this directive if you know you'll 
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See also 
Example 



never run programs using an 8087 coprocessor. This 
directive causes floating-point instructions to be 
optimized in a manner incompatible with the 8087, so 
don't use it if you want your programs to run using an 
8087. (Same as P387.) 

.8087, .287, 8087, PN087, P287, P387 



.387 
fsin 



;SIN() only available on 387 



.8086 



Function 
Mode 
Syntax 
Remarks 



See also 



Enables assembly of 8086 instructions only 
MASM 

.8086 

.8086 enables assembly of the 8086 instructions and dis- 
ables all instructions available only on the 80186, 80286, 
and 80386 processors. It also enables the 8087 copro- 
cessor instructions exactly as if the .8087 or 8087 had 
been issued. 

This is the default instruction set mode used by Turbo 
Assembler when it starts assembling a source file. 
Programs assembled using this mode will run on all 
members of the 80x86 processor family. If you know that 
your program will only be run on one of the more 
advanced processors, you can take advantage of the 
more sophisticated instructions of that processor by 
using the directive that enables that processor's 
instructions. (Same as P8086.) 

186, .286C, .286, .286P, .386C, .386, .386P, P8086, P286, 
P286N, P286P, P386, P386N, P386P 



.8087 



Function 

Mode 

Syntax 



Enables assembly of 8087 coprocessor instructions 
MASM 

.8087 
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Remarks 



See also 
Example 



.8087 enables all the 8087 coprocessor instructions, and 
disables all those coprocessor instructions available only 
on the 80287 and 80387. 

This is the default coprocessor instructions set used by 
Turbo Assembler. Programs assembled using this mode 
will run on all members of the 80x87 coprocessor family. 
If you know that your program will only be run on one 
of the more advanced coprocessors, you can take advan- 
tage of the more sophisticated instructions of that 
processor by using the particular directive that enables 
that processor's instructions. (Same as P8087.) 

.287, .387, 8087, PN087, P287, P387 



.8087 

fstsw MEMLOC 



;no FSTSW AX on 8087 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Defines a near code label 
MASM, Ideal 



name is a symbol that you have not previously defined 
in the source file. You can place a near code label on a 
line by itself or at the start of a line before an instruction. 
You usually use a near code label as the destination of a 
JMP or CALL instruction from within the same 
segment. 

The code label will only be accessible from within the 
current source file unless you use the PUBLIC directive 
to make it accessible from other source files. 

This directive is the same as using the LABEL directive 
to define a NEAR label; for example A: is the same as A 
LABEL NEAR. 

LABEL 



jne A 
inc si 



A: 



;skip following instruction 
;JNE goes here 
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Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Defines a numeric equate 
MASM, Ideal 

name = expression 

name is assigned the result of evaluating expression, 
which must evaluate to either a constant or an address 
within a segment, name can either be a new symbol 
name, or a symbol that was previously defined using the 
= directive. 

You can redefine a symbol that was defined using the = 
directive, allowing you to use the symbols as counters. 
(See the example that follows.) 

You can't use = to assign strings or to redefine keywords 
or instruction mnemonics; you must use EQU to do 
these things. 

The = directive has far more predictable behavior than 
the EQU directive in MASM mode, so you should use = 
instead of EQU wherever you can. 



EQU 



BitMask = 1 
BittBl LABEL BYTE 

REPT 8 

DB BitMask 
BitMask = BitMask * 2 

ENDM 



/initialize bit mask 



/shift the bit to left 



ALIGN 



Function 

Mode 

Syntax 

Remarks 



Rounds up the location counter to a power-of-two 
address 

MASM, Ideal 

ALIGN boundary 

boundary must be a power of 2 (for example, 2, 4, 8, and 
so on). 

If the location counter is not already at an offset that is a 
multiple of boundary, single byte NOP instructions are 
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See also 
Example 



inserted into the segment to bring the location counter 
up to the desired address. If the location counter is 
already at a multiple of boundary, this directive has no 
effect. 

You can't reliably align to a boundary that is more strict 
than the segment alignment in which the ALIGN 
directive appears. The segment's alignment is specified 
when the segment is first started with the SEGMENT 
directive. 

For example, if you have defined a segment with 

CODE SEGMENT PARA PUBLIC 

you can say ALIGN 16 (same as PARA) but you can't 
say ALIGN 32, since that is more strict than the align- 
ment indicated by the PARA keyword in the 
SEGMENT directive. ALIGN generates a warning if the 
segment alignment is not strict enough. 

EVEN, EVENDATA 



ALIGN 4 

BigNum DD 12345678 



; align to DWORD boundary for 386 



.ALPHA 



Function 
Mode 
Syntax 
Remarks 



Sets alphanumeric segment-ordering 
MASM 

.ALPHA 

You usually use .ALPHA to ensure compatibility with 
very old versions of MASM and the IBM assembler. The 
default behavior of these old assemblers is to emit seg- 
ments in alphabetical order, unlike the newer versions. 
Use this option when you assemble source files written 
for old assembler versions. 

If you don't use this directive, the segments are ordered 
in the same order that they were encountered in the 
source file. The DOSSEG directive can also affect the 
ordering of segments. 

.ALPHA does the same thing as the /A command-line 
option. If you used the /S command-line option to force 
sequential segment-ordering, .ALPHA will override it. 
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See also 
Example 



DOSSEG, . 


SEQ, 




.ALPHA 




XYZ 


SEGMENT 




XYZ 


ENDS 




ABC 


SEGMENT 


;tf 


ABC 


ENDS 





;this segment will be first 



ARG 



Function 

Mode 

Syntax 

Remarks 



Sets up arguments on the stack for procedures 

MASM, Ideal 

a rg argument [, argument] ... [=sywbol] [RETURNS 
argument [, argument]] 

ARG usually appears within a PROC/ENDP pair, 
allowing you to access arguments pushed on the stack 
by the caller of the procedure. Each argument is assigned 
a positive offset from the BP register, presuming that 
both the return address of the function call and the 
caller's BP have been pushed onto the stack already. 

argument describes an argument the procedure is caUed 
with. The language specified with the .MODEL directive 
determines whether the arguments are in reverse order 
on the stack. You must always list the arguments in the 
same order they appear in the high-level language 
function that calls the procedure. Turbo Assembler 
reads them in reverse order if necessary. Each argument 
has the following syntax: 

argnamel [countl] ] ['.[distance] PTR] type] [:count2] 

argname is the name you'U use to refer to this argument 
throughout the procedure, distance is optional and can 
be either NEAR or FAR to indicate that the argument is 
a pointer of the indicated size, type is the data type of the 
argument and can be BYTE, WORD, DATAPTR, 
DWORD, FWORD, PWORD, QWORD, TBYTE, or a 
structure name, countl and countl are the number of 
elements of the specified type. The total count is 
calculated as countl * countl. 

If you don't specify type, WORD is assumed. 
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If you add PTR to indicate that the argument is in fact a 
pointer to a data item. Turbo Assembler emits this 
debug information for Turbo Debugger. Using PTR only 
affects the generation of additional debug information, 
not the code Turbo Assembler generates. You must still 
write the code to access the actual data using the pointer 
argument. 

If you use PTR alone, without specifying NEAR or FAR 
before it. Turbo Assembler sets the pointer size based on 
the current memory model and, for the 386 processor, 
the current segment address size (16 or 32 bit). The size 
is set to WORD in the tiny, small, and medium memory 
models and to DWORD for all other memory models 
using 16-bit segments. If you're using the 386 and are in 
a 32-bit segment, the size is set to DWORD for tiny, 
small, and medium models and to FWORD for compact, 
large, and huge models. 

The argument name variables remain defined within the 
procedure as BP-relative memory operands. For 
example. 

Fund PROC NEAR 

ARG A: WORD, B : DWORD: 4, C: BYTE = D 

defines A as [BP+4], B as [BP+61 C as [BP+14], and D as 
20. 

Argument names that begin with the local symbol prefix 
when local symbols are enabled are limited in scope to 
the current procedure. 

If you end the argument list with an equal sign (=) and a 
symbol, that symbol will be equated to the total size of the 
argument block in bytes. You can then use this value at 
the end of the procedure as an argument to the RET 
instruction, which effects a stack cleanup of any pushed 
arguments before returning (this is the Pascal calling 
convention). 

Since it is not possible to push a byte-sized argument on 
the 8086 processor family, any arguments declared of 
type BYTE are considered to take 2 bytes of stack space. 
This agrees with the way high-level languages treat 
character variables passed as parameters. If you really 
want to specify an argument as a single byte on the 
stack, you must explicitly supply a coimt field, as in 
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ARG REALBYTE:BYTE:1 

If you don't supply a count for BYTE arguments, a 
count of 2 is presumed. 

The optional RETURNS keyword introduces one or 
more arguments that won't be popped from the stack 
when the procedure returns to its caller. Normally, if 
you specify the language as PASCAL or TPASCAL 
when using the .MODEL directive, all arguments are 
popped when the procedure returns. If you place 
arguments after the RETURNS keyword, they will be 
left on the stack for the caller to make use of, and then 
pop. In particular, you must define a Pascal string return 
value by placing it after the RETURNS keyword. 

LOCAL, PROC, USES 

A sample Pascal procedure: 



fp PROC FAR 

ARG SRC: WORD, DEST: WORD 

push bp 

mov bp,sp 

mov di,DEST 

mov si, SRC 

;<Procedure body> 

pop bp 

ret ARGLEN 
fp ENDP 



ARGLEN 



ASSUME 



Function 

Mode 
Syntax 

Remarks 



Associates segment register with segment or group 
name 

MASM, Ideal 

ASSUME segment reg: name [, segment reg: name ].. . 
ASSUME segr/nefitreg:NOTHING 
ASSUME NOTHING 

segmentreg is one of CS, DS, ES, or SS registers and, if 
you have enabled the 80386 processor with the P386 or 
P386N directives, the FS and GS registers. 

name can be one of the following: 
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B the name of a group as defined using the GROUP 
directive 

■ the name of a segment as defined using the 
SEGMENT directive or one of the simplified 
segmentation directives 

B an expression starting with the SEG operator 

B the keyword NOTHING 

The NOTHING keyword cancels the association 
between the designated segment register and segment 
or group name. The ASSUME NOTHING statement 
removes all associations between segment registers and 
segment or group names. 

You can set multiple registers in a single ASSUME 
statement, and you can also place multiple ASSUME 
statements throughout your source file. 

See "The ASSUME Directive" in Chapter 10 of the User's 
Guide for a complete discussion of how to use the 
ASSUME directive. 

GROUP, SEGMENT 

DATA SEGMENT 
mov ax, DATA 
mov ds,ax 
ASSUME ds:DATA 



%BIN 



Function 
Mode 
Syntax 
Remarks 

Example 



Sets the width of the object code field in the listing file 
MASM, Ideal 

%BIN size 

size is a constant. If you don't use this directive, the 
instruction opcode field takes up 20 columns in the 
listing file. 

%BIN 12 ;set listing width to 12 columns 
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CATSTR 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Concatenates several strings to form a single string 
MASM51, Ideal 

name CATSTR string[, string] . .. 

name is given a value consisting of all the characters 
from each string combined into a single string. 

Each string may be one of the following: 

■ a string argument enclosed in angle brackets, like 
<aho 

■ a previously defined text macro 

■ a numeric string substitution starting with percent (%) 

SUBSTR, INSTR, SIZESTR 

LETTERS CATSTR <abc>,<def> /LETTERS = "abcdef" 



.CODE 



Function 
Mode 
Syntax 
Remarks 



Defines the start of a code segment 
MASM 

.CODE [name] 

The .CODE directive indicates the start of the executable 
code in your module. You must first have used the 
.MODEL directive to specify a memory model. If you 
specify the medium or large memory model, you can 
follow the .CODE directive with an optional name that 
indicates the name of the segment. This way you can put 
multiple code segments in one file by giving them each a 
different name. 

You can place as many .CODE directives as you want in 
a source file. All the different pieces with the same name 
will be combined to produce one code segment exactly 
as if you had entered all the code at once after a single 
.CODE directive. 

Using the .CODE directive allows the CS register to 
access the current code segment. This behavior is exactly 
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See also 



Example 



as if you had put this directive after each .CODE 
directive in your source file: 

ASSUME cs:@code 

CODESEG, .DATA, .FARDATA, .FARDATA?, 
.MODEL, .STACK, .DATA, .FARDATA, .FARDATA?, 
.MODEL, .STACK 



.CODE 
mov al,X 
.DATA 
X DB ? 



;here comes the code 
; switch to data segment 



CODESEG 



Function 
Mode 
Remarks 
See also 



Defines the start of the code segment 

MASM, Ideal 

CODESEG is the same as .CODE. 

CODE, .DATA, .FARDATA, .FARDATA?, .MODEL, 
.STACK 



COMM 



Function 
Mode 
Syntax 
Remarks 



Defines a communal variable 
MASM, Ideal 

COM definition [,definition] .. . 

Each definition describes a symbol and has the following 
format: 

[distance] name:type [icount] 

distance is optional and can be either NEAR or FAR. It 
specifies whether the communal variable is part of the 
near data space (D GROUP) or whether it occupies its 
own far segment. If you do not specify a distance, it will 
default to the size of the default data memory model. If 
you are not using the simplified segmentation directives 
(.MODEL, and so on), the default size is NEAR. With 
the tiny, small, and medium models, the default size is 
also NEAR; all other models are FAR. 



Chapter 3, Directives 



65 



name is the symbol that is to be communal and have 
storage allocated at link time, type can be one of the 
following: BYTE, WORD, DATAPTR, DWORD, 
FWORD, PWORD, QWORD, TBYTE, or a structure 
name. 

The optional count specifies how many items this 
communal symbol defines. If you do not specify a count, 
one is assumed. The total space allocated for the com- 
munal variable is the count times the length specified by 
the type field. 

You can define more than one communal symbol by 
separating each definition with a comma (,). 

Commimal variables are allocated by the linker. 

In MASM mode, communal symbols declared outside of 
any segment are presumed to be reachable via the DS 
register, which may not always be a valid assumption. 
Make sure that you either place the correct segment 
value in DS or use an explicit segment override when 
referring to these variables. In Ideal mode. Turbo 
Assembler correctly checks for whether the communal 
variable is addressable, using any of the current segment 
registers as described with the ASSUME directive. 

Communal variables can't be initialized. Use the 
GLOBAL directive if you wish to initialize data items 
that are to be shared between modules. The linker also 
doesn't guarantee the allocation of communal variables 
in any particular order, so you can't make assumptions 
about data items allocated by COMM directives on 
sequential source lines. 

See also EXTRN, GLOBAL, PUBLIC 

Example com buffer: byte : 512 ;allocated at link time 

COMMENT 



Function 


Starts a comment block 


Mode 


MASM 


Syntax 


COMMENT delimiter [text] 




[text] 




delimiter 
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Remarks 



Example 



COMMENT ignores all text between the first delimiter 
character and the line containing the next occurrence of 
the delimiter, delimiter is the first nonblank character 
after the COMMENT directive. 

COMMENT * 

Any old stuff 



%CONDS 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Shows all statements in conditional blocks in the listing 
MASM, Ideal 

%CONDS 

%CONDS is the default conditional listing mode if you 
don't use any listing control directives. (Same as 
.LFCOND.) 

When %CONDS is in effect, the listing will show all 
statements within conditional blocks, even those blocks 
that evaluate as false and don't result in the evaluation 
of enclosed statements. 

%NOCONDS, .LFCOND, .SFCOND, .TFCOND 



%CONDS 
IF 

mov ax,l 
ENDIF 



;in listing, despite "IF 0" above 



.CONST 



Function 
Mode 
Syntax 
Remarks 



Defines constant data segment 
MASM 

.CONST 

The .CONST directive indicates the start of the segment 
in your program containing constant data. This is data 
your program requires, but it will not be changed when 
the program executes. You can put things such as 
prompt and message strings in this segment. 
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See also 
Example 



You don't have to use this directive when writing an 
assembler-only program. It exists so that you can write 
routines that interface to high-level languages and then 
use this for initializing constant data. 

.CODE, .DATA, .DATA?, .FARDATA, .FARDATA?, 
.MODEL 

.CONST 

MSG DB "Execution terminated" 



CONST 



Function 
Mode 
See also 



Defines constant data segment 

MASM, Ideal 

.CODE, .CONST, .DATA, DATA?, .FARDATA, 
.FARDATA? 



.CREF 



Function 
Mode 
Syntax 
Remarks 



See also 



Enables cross-reference listing (CREF) 
MASM 

.CREF 

.CREF allows cross-reference information to be accumu- 
lated for all symbols encountered from this point 
forward in the source file. This directive reverses the 
effect of any %XCREF or .XCREF directives that 
inhibited the collection of cross-reference information. 

Turbo Assembler includes cross-reference information 
in the listing file, as well as in a separate .XRF file. 

%CREF 



%CREF 



Function 

Mode 

Syntax 



Enables cross-reference listing (CREF) 
MASM, Ideal 

%CREF 
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%NOCREF, .CREF, .XCREF, %CREFALL, %CREFREF, 
%CREFUREF 



%CREF 
WVAL DW 



;CREF shows WVAL defined here 



%CREFALL 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Lists all symbols in cross-reference 
MASM, Ideal 

%CREFALL 

%CREFALL reverses the effect of any previous 
%CREFREF or %CREFUREF directives that disabled 
the listing of unreferenced or referenced symbols. After 
issuing %CREFALL, all subsequent symbols in the 
source file will appear in the cross-reference listing. 

By default. Turbo Assembler uses this mode when 
assembling your source fQe. 

%CREFREF, %CREFUREF 



%CREFREF 

ARGl EQU [bp+4] 

%CREFALL 

ARG2 EQU [bp+6] 

ARG3 EQU [bp+8] 

mov ax,ARG3 

END 



;not referenced, won't be in listing 

;not referenced, appears anyway 
/referenced, appears in listing 



%CREFREF 



Function 

Mode 

Syntax 

Remarks 



See also 



Disables listing of unreferenced symbols in cross- 
reference 

MASM, Ideal 

ICREFREF 

%CREFREF causes symbols that are defined but never 
referenced to be omitted from the cross-reference listing. 
Normally when you request a cross-reference, these 
symbols appear in the symbol table. 

%CREF, %CREFUREF, %CREFALL 
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Example 



%CREF 
abc EQU 4 
xyz EQU 1 
mov ax, xyz 

END 



;will not appear in CREF listing 
/will appear in listing 
;makes XYZ appear in listing 



%CREFUREF 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Lists only the unreferenced symbols in cross-reference 
MASM, Ideal 

%CREFUREF 

%CREFUREF enables the listing of unreferenced sym- 
bols in the symbol table cross-reference. When you use 
this directive, only unreferenced symbols appear in the 
symbol table. To see both referenced and unreferenced 
symbols, use the % CREF ALL directive. 

%CREFALL, %CREFREF 

%CREF 

abc EQU 2 ; doesn't appear in listing 

%CREFUREF 

def EQU 1 /appears in listing 

END 



%CTLS 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Prints listing controls 
MASM, Ideal 



%CTLS 



%CTLS causes listing control directives (such as %LIST, 
%INCL, and so on) to be placed in the listing file; 
normally, they are not listed. It takes effect on all 
subsequent lines, so the %CTLS directive itself will not 
appear in the listing file. 



%NOCTLS 



%CTLS 
%NOLIST 



/this will be in listing file 
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.DATA 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Defines the start of a data segment 
MASM 

.DATA 

The .DATA directive indicates the start of the initialized 
data in your module. You must first have used the 
.MODEL directive to specify a memory model. 

You can place as many .DATA directives as you want in 
a source file. All the different pieces will be combined to 
produce one data segment, exactly as if you had entered 
all the data at once after a single .DATA directive. 

The data segment is put in a group called D GROUP, 
which also contains the segments defined with the 
.STACK, .CONST, and .DATA? directives. You can 
access data in any of these segments by making sure that 
one of the segment registers is pointing to D GROUP. 

See the .MODEL directive for complete information on 
the segment attributes for the data segment. 

.CODE , .CONST, .DATA?, DATASEG, .FARDATA, 
.FARDATA?, .MODEL, .STACK 



.DATA 

ARRAYl DB 100 DUP (0) 



;NEAR initialized data 



.DATA? 



Function 
Mode 
Syntax 
Remarks 



Defines the start of an uninitialized data segment 
MASM 

.DATA? 

The .DATA? directive indicates the start of the unini- 
tialized data in your module. You must first have used 
the .MODEL directive to specify a memory model. 

You create uninitialized data using the DUP operator 
with the ? symbol. For example, 

DB 6 DUP (?) 
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See also 
Example 



You do not have to use this directive when v^riting an 
assembler-only program. It exists so that you can write 
routines that interface to high-level languages and then 
use this directive for uninitialized data. 

You can place as many .DATA? directives as you want 
in a source file. All the pieces will be combined to pro- 
duce one data segment, exactly as if you had entered all 
the data at once after a single .DATA? directive. 

The uninitialized data segment is put in a group called 
DGROUP, which also contains the segments defined 
with the .STACK, .CONST, and .DATA directives. 

See .MODEL for complete information on the segment 
attributes for the uninitialized data segment. 

.CODE, .CONST, .DATA, .FARDATA, .FARDATA?, 
.MODEL, .STACK 



.DATA? 

TEMP DD 4 DUP (?) 



/uninitialized data 



DATASEG 



Function 
Mode 
Syntax 
Remarks 

See also 



Defines the start of a data segment 
MASM, Ideal 

DATASEG 

DATASEG is the same as .DATA. It must be used in 
Ideal mode only. 

.CODE , .CONST, .DATA, .DATA?, .FARDATA, 
.FARDATA?, .MODEL, .STACK 



DB 



Function 
Mode 
Syntax 
Remarks 



Allocates byte-size storage 
MASM, Ideal 

[name] DB expression [, express ion]... 

name is the symbol you'll subsequently use to refer to 
the data. If you don't supply a name, the data will be 
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allocated, but you won't be able to refer to it using a 
symbolic name. 

Each expression allocates one or more bytes and can be 
one of the following: 

■ A constant expression that has a value between -128 
and 255. 

■ The question mark (?) indeterminate initialization 
symbol; this allocates storage without giving it a 
specific value. 

■ A character string of one or more characters. 

■ A repeated expression using the DUP operator. 

DD, DF, DP, DQ, DT, DW 

fibs DB 1,1,2,3,5,8,13 

BUF DB 80 DUP (?) 

MSG DB "Enter value: " 



DD 



Function 
Mode 
Syntax 
Remarks 



Allocates doubleword-sized storage 
MASM, Ideal 

[name] DD [type PTR] expression [/expression]... 

name is the symbol you'll subsequently use to refer to 
the data. If you don't supply a name, the data wiU be 
allocated, but you won't be able to refer to it using a 
symbolic name. 

type followed by PTR is optional. It adds debug 
information to the symbol being defined, so that Turbo 
Debugger can display its contents properly. It has no 
effect on the data generated by Turbo Assembler, type 
can be one of the following: BYTE, WORD, DATAPTR, 
DWORD, FWORD, PWORD, QWORD, TBYTE, 
SHORT, NEAR, FAR or a structure name. For example, 

person STRUC 

name DB 32 DUP(?) 

age DW ? 

person ENDS 

PPTR DD person PTR ;PPTR is a far pointer 

; to the structure 
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Each expression allocates one or more doublewords 
(4 bytes) and may be one of the following: 

■ A constant expression that has a value between 
-2,147,483,648 and 4,294,967,295. 

■ A short (32-bit) floating-point number. 

■ The question mark (?) indeterminate initialization 
sjonbol; this allocates storage without giving it a 
specific value. 

■ An address expression, specifying a far address in a 
16-bit segment (segment:offset) or a near address in a 
32-bit segment (32-bit offset only). 

■ A repeated expression using the DUP operator. 



See also 


DB, DF, DP, DQ, DT, DW 




Example 


Data 32 SEGMENT USE32 
Xarray DB 0,1,2,3 
Data32 ENDS 
Data SEGMENT 






Consts DD 3.141, 2.718 


floating-point constants 




DblPtr DD Consts 


16-bit far pointer 




NrPtr DD Xarray 


•32-bit near pointer 




Bigint DD 12345678 


large integer 




Darray DD 4 DUP (1) 


•4 integers 



% DEPTH 



Function 
Mode 
Syntax 
Remarks 



Sets size of depth field in listing file 
MASM, Ideal 

%DEPTH width 

width specifies how many columns to reserve for the 
nesting depth field in the listing file. The depth field 
indicates the nesting level for INCLUDE files and macro 
expansions. If you specify a width of 0, this field does 
not appear in the listing file. Usually, you won't need to 
specify a width of more than 2, since that would display 
a depth of up to 99 without truncation. 

The default width for this field is 1 column. 



Example 



%DEPTH 2 



;show nesting levels > 9 
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DF 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Defines far 48-bit pointer (6 byte) data 
MASM, Ideal 

[name] DF [type PTR] expression [, express ion] . .. 

name is the symbol you'U subsequently use to refer to 
the data. If you don't supply a name, the data will be 
allocated, but you won't be able to refer to it using a 
symbolic name. 

type followed by PTR is optional. It adds debug 
information to the symbol being defined, so that Turbo 
Debugger can display its contents properly. It has no 
effect on the data generated by Turbo Assembler, type 
can be one of the following: BYTE, WORD, DATAPTR, 
DWORD, FWORD, FWORD, QWORD, TBYTE, 
SHORT, NEAR, FAR or a structure name. For example. 



person STRUC 

name DB 32 dup(?) 

age DW ? 

person ENDS 

DATA SEGMENT USE32 

PPTR DF person PTR 

; to the structure 



;PPTR is a 32-bit far pointer 



Each expression allocates one or more 48-bit far pointers 
(6 bytes) and may be one of the following: 

B A constant expression that has a value between 
-140,737,488,355,328 and 281,474,976,710,655. 

■ The question mark (?) indeterminate initialization 
symbol; this allocates storage without giving it a 
specific value. 

D An address expression, specifying a far address in a 
48-bit segment (segment:48-bit offset). 

■ A repeated expression using the DUP operator. 

This directive is normally used only with the 30386 
processor. 

DB, DD, DP, DQ, DT, DW 



DATA 



.386 

SEGMENT USE32 



Chapters, Directives 



75 



MSG DB 


"All done" 




FmPtr DF 


MSG 


;FAR pointer to MSG 


DATA ENDS 







DISPLAY 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Outputs a quoted string to the screen 
Ideal, MASM 

DISPLAY "text" 

text is any message you want to display; you must sur- 
round it with quotes ("")• The message is written to the 
standard output device, which is usually the screen. If 
you wish, you can use the DOS redirection facility to 
send screen output to a file. 

Among other things, you can use this directive to inform 
yourself of the generation of sections of conditional 
assembly. 

%OlJT 

DISPLAY "Assembling EGA interface routines" 



DOSSEG 



Function 
Mode 
Syntax 
Remarks 



Enables DOS segment-ordering at link time 
MASM, Ideal 

DOSSEG 

You usually use DOSSEG in conjunction with the 
.MODEL directive, which sets up the simplified seg- 
mentation directives. DOSSEG tells the linker to order 
the segments in your program the same way high-level 
languages order their segments. 

You should only use this directive when you are writing 
stand-alone assembler programs, and then you only 
need to use the DOSSEG directive once in the main 
module that specifies the starting address of your 
program. 

Segments appear in the following order in the execut- 
able program: 
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See also 
Example 



1. All segments that have the class name 'CODE'. 

2. All segments that do not have the class name 'CODE' 
and are not in the group named D GROUP. 

3. All segments in D GROUP in the following order: 

a. All segments that have the class name 
'BEGDATA'. 

b. All segments that do not have the class name 
'BEGDATA', 'BSS', or 'STACK'. 

c. All segments with a class name of 'BSS'. 

d. All segments with a class name of 'STACK'. 

.MODEL 

DOSSEG 
.MODEL medium 



DP 



Function 
Mode 
See also 



Defines a far 48-bit pointer (6 byte) data area 

MASM, Ideal 

DB, DD, DF, DQ, DT, DW 



DQ 



Function 
Mode 
Syntax 
Remarks 



Defines a quadword (8 byte) data area 
MASM, Ideal 

[name] DQ expression [, expression] .. . 

name is the symbol you'll subsequently use to refer to 
the data. If you don't supply a name, the data will be 
allocated, but you won't be able to refer to it using a 
symbolic name. 

Each expression allocates one or more quadwords 
(8 bytes) and can be one of the following: 

■ A constant expression that has a value between -2^^ 
and 2^-1. 

■ A long (64-bit) floating-point number. 
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See also 
Example 



■ The question mark (?) indeterminate initialization 
symbol; this allocates storage without giving it a 
specific value. 

■ A repeated expression using the DUP operator. 

DB, DD, DF, DP, DT, DW 

Hugint DQ 314159265358979323 
BigFlt DQ 1.2345678987654321 
Qarray DQ 10 DUP (?) 



DT 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Defines a 10-byte data area 
MASM, Ideal 

[name] DT expression [, expression] .. . 

name is the symbol you'll subsequently use to refer to 
the data. If you don't supply a name, the data will be 
allocated, but you won't be able to refer to it using a 
symbolic name. 

Each expression allocates one or more 10-byte values and 
may be one of the following: 

■ A constant expression that has a value between -2'^^ 
and 280-1. 

■ A packed decimal constant expression that has a value 
between and 99,999,999,999,999,999,999. 

■ The question mark (?) indeterminate initialization 
symbol; this allocates storage without giving it a 
specific value. 

■ A 10-byte temporary real formatted floating-point 
number. 

■ A repeated expression using the DUP operator. 
DB, DD, DF, DP, DQ, DW 



PakNum DT 123456 
TerapVal DT 0.0000000001 



; beware — packed decimal 
;high precision FP 
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DW 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Defines a word-size (2 byte) data area 
MASM, Ideal 

[name] DW [type PTR] expression [, expression] .. . 

name is the symbol you'll subsequently use to refer to 
the data. If you don't supply a name, the data will be 
allocated, but you won't be able to refer to it using a 
symbolic name. 

type followed by PTR is optional. It adds debug 
information to the symbol being defined, so that Turbo 
Debugger can display its contents properly. It has no 
effect on the data generated by Turbo Assembler, type 
can be one of the following: BYTE, WORD, DATAPTR, 
DWORD, FWORD, PWORD, QWORD, TBYTE, 
SHORT, NEAR, FAR or a structure name. For example. 



Narray DW 100 DUP (?) 
NPTR DW WORD PTR narray 
; to a word 



;NPTR is a near pointer 



Each expression allocates one or more words (2 bytes) 
and may be one of the following: 

■ A constant expression that has a value between 
-32,767 and 65,535. 

■ The question mark (?) indeterminate initialization 
symbol; this allocates storage without giving it a 
specific value. 

■ An address expression, specifying a near address in a 
16-bit segment (offset only). 

B A repeated expression using the DUP operator. 
DB, DD, DF, DP, DQ, DT 



int DW 12345 
Wbuf DW 6 DUP (?) 
Wptr DW Wbuf 



; 16-bit integer 

;6 word buffer 

;offset~only pointer to WBUF 
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ELSE 



Function 

Mode 

Syntax 



Remarks 



See also 
Example 



Starts alternative conditional assembly block 
MASM, Ideal 

IF condition 

statements! 

[ELSE 

statements^] 

ENDIF 

The statements introduced by ELSE are assembled if the 
condition associated with the IF statement evaluates to 
false. This means that either statements! will be 
assembled or statements! will be assembled, but not 
both. 

The ELSE directive always pairs with the nearest 
preceding IF directive that's not already paired with an 
ELSE directive. 

ENDIF, IF, IFl, IF2, IFB, IFDEF, IFDIF, IFDIFI, IFE, 
IHDN, IFIDNI, IFNB, IFNDEF 

IF LargeModel EQ 1 

les di,ADDR 
ELSE 

lea di,ADDR 
ENDIF 



ELSEIF 



Function 

Mode 

Syntax 

Remarks 



Starts nested conditional assembly block if an expression 
is True 

MASM, Ideal 

ELSEIF expression 

expression must evaluate to a constant and cannot con- 
tain any forward-referenced symbol names. If expression 
evaluates to a nonzero value, the statements within the 
conditional block are assembled, as long as the 
conditional directive (IF, and so on) preceding the 
ELSEIF evaluated to False. 
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See also 



Example 



You may have any number of ELSEIF directives in a 
conditional block. As soon as an ELSEIF is encountered 
that has a true expression, that block of code is as- 
sembled, and all other parts of the conditional block 
defined by ELSEIF or ELSE are skipped. You can also 
mix the various ELSExa: directives in the same con- 
ditional block. 

ELSEIFl, ELSEIF2, ELSEIFB, ELSEIFDEF, ELSEIFDIF, 
ELSEIFDIFI, ELSEIFE, ELSEIFIDN, ELSEIFIDNI, 
ELSEIFNB, ELSEIFNDEF 

IF ARGSIZE EQ 1 

mov al,argname 
ELSEIF ARGSIZE EQ 2 

mov ax,argname 
ELSE 

%OUT BAD ARGSIZE 
ENDIF 



EMUL 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Generates emulated coprocessor instructions 
MASM, Ideal 

EMUL 

Turbo Assembler normally generates real floating-point 
instructions to be executed by an 80x87 coprocessor. Use 
EMUL if your program has installed a software 
floating-point emulation package, and you wish to 
generate instructions that will use it. EMUL has the 
same effect as specifying the /e command-line option. 

You can combine EMUL with the NOEMUL directive 
when you wish to generate real floating-point 
instructions in one portion of a file and emulated 
instructions in another portion. 

NOEMUL 



Finit 
EMUL 
Fsave BUF 



;real 8087 coprocessor instruction 
/emulated instruction 
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END 



Function 
Mode 
Syntax 
Remarks 



Example 



Marks the end of a source file 
MASM, Ideal 

END [startaddress] 

startaddress is an optional symbol or expression that 
specifies the address in your program where you want 
execution to begin. If your program is linked from 
multiple source files, only one file may specify a start- 
address, startaddress may be an address within the 
module; it can also be an external symbol defined in 
another module, declared with the EXTRN directive. 

Turbo Assembler ignores any text after the END 
directive in the source file. 

.MODEL small 

.CODE 

START: 

;Body of program goes here 

END START /program entry point is "START" 

THIS LINE IS IGNORED 

SO IS THIS ONE 



ENDIF 



Function 

Mode 

Syntax 

Remarks 

See also 
Example 



Marks the end of a conditional assembly block 
MASM, Ideal 

IF condition 

statements 

ENDIF 

All conditional assembly blocks started with one of the 
IFjcxxx directives must end with an ENDIF directive. 
You can nest IF blocks up to 255 levels deep. 

ELSE, IF, IFl, IF2, IFB, IFDEF, IFDIF, IFDIFI, IFE, 
IFIDN, IFIDNI, IFNB, IFNDEF 



IF DebugMode 
mov ax,0 
call DebugDump 

ENDIF 



/•assemble following if debug mode not 
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ENDM 

Function 
Mode 
Syntax 
Remarks 

See also 
Example 



Indicates the end of a repeat block or a macro 
MASM, Ideal 

ENDM 

The ENDM directive identifies the end of the macro 
definition or a repeat block. 

IRP, IRPC, MACRO, REPT 

IRP reg,<ax,bx,cx,dx> 
push reg 

ENDM 



ENDP 



Function 


Indicates the end of a procedure 


Mode 


MASM, Ideal 


Syntax 


MASM mode: 




[procname] ENDP 




Ideal mode: 




ENDP [procname] 



Remarks 



See also 
Example 



If you supply the optional procname, it must match the 
procedure name specified with the PROC directive that 
started the procedure definition. 

Notice that in Ideal mode, the optional procname comes 
after the ENDP. 

ENDP does not generate a RET instruction to return to 
the procedure's caller; you must explicitly code this. 

ARG, LOCAL, PROC 

Loadit PROC 

;Body of procedure 

ret 
Loadit ENDP 
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ENDS 



Function 

Mode 

Syntax 



Remarks 



See also 
Example 



Marks end of current segment structure or union 
MASM, Ideal 
MASM mode: 

[segmentname] ENDS 
[strucname] ENDS 

Ideal mode: 

ENDS [segmentname] 
ENDS [strucname] 

ENDS marks the end of either a segment, structure, or 
union. If you supply the optional segmentname, it must 
match the segment name specified with the matching 
SEGMENT directive. Likewise, the optional strucname 
must match the structure name specified with the 
matching STRUC or UNION directive. 

Notice that in Ideal mode, the optional name comes after 
the ENDS. 

SEGMENT, STRUC, UNION 

DATA SEGMENT ; start of data segment 

Barray DB 10 DUP (0) 

DATA ENDS ;end of data segment, 

; optional "data" included 
STAT STRUC 
Mode DW ? 
FuncPtr DD ? 



ENDS 



/end of structure definition 



EQU 



Function 
Mode 
Syntax 
Remarks 



Defines a string, alias, or numeric equate 
MASM, Ideal 

name EQU expression 

name is assigned the result of evaluating expression, name 
must be a new symbol name that has not previously 
been defined in a different manner. In MASM mode, you 
can only redefine a symbol that was defined using the 
EQU directive if it was first defined as a string equate. 



84 



Turbo Assembler Reference Guide 



See also 
Example 



In MASM mode, EQU can result in one of three kinds of 
equates being generated: 

■ Alias: Redefines keywords or instruction mnemonics, 
and also allows you to assign alternative names to 
other symbols you have defined. Alias EQUs can be 
redefined. 

B Expression: Evaluates to a constant or address, much 
like when using the = directive. 

■ String: expression is stored as a text string to be 
substituted later when name appears in expressions. 
When expression cannot be evaluated as an alias, 
constant, or address, it becomes a string expression. 
String EQUs can be redefined. 



BlkSize EQU 512 

BufBlks EQU 4 

BufSize EQU BlkSize*BufBlks 

BufLen EQU BufSize ;alias for BUFSIZE 

DoneMsg EQU <' Returning to DOS'> 



.ERR 



Function 
Mode 
Syntax 
Remarks 



See also 



Example 



Forces an error message 
MASM 

.ERR 

.ERR causes an error message to occur at the line it is 
encountered on in the source file. 

You usually use this directive inside a conditional 
assembly block that tests whether some assemble-time 
condition has been satisfied. 

.ERRl, .ERR2, .ERRE, .ERRNZ, .ERRNDEF, .ERRDEF, 
.ERRB, .ERRNB, .ERRIDN, .ERRIDNI, .ERRDIF, 
.ERRDIFI 



IF $ GT 400h 

.ERR 

%OUT Segment too big 
ENDIF 



; segment too big 
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ERR 



Function 


Forces an error message 


Mode 


MASM, Ideal 


Syntax 


ERR 


Remarks 


Same as .ERR. 


See also 


.ERRl, .ERR2, .ERRE, .1 



.ERRB, .ERRNB, .ERRIDN, .ERRIDNI, .ERRDIF, 
.ERRDIFI 



.ERRl 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Forces an error message on pass 1 
MASM 

.ERRl 

Since Turbo Assembler is a single-pass assembler, the 
fact that .ERRl forces a message on pass 1 means that 
the error message is forced on the assembly pass. This 
means that the error message will appear on the screen 
but will not appear in the listing fUe, which is generated 
during a second pass. (This directive would have a 
different meaning with a two-pass assembler.) 

Again, since this is a single-pass assembler, this directive 
also generates a warning message so that you know it's 
pass-dependent and may not work as you expect. 

.ERR2 

.ERRl ;this won't appear in listing 



.ERR2 



Function 
Mode 
Syntax 
Remarks 



Forces an error message on pass 2 
MASM 

.ERR2 

Since Turbo Assembler is a single-pass assembler, the 
fact that this forces a message on pass 2 means that it's 
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See also 
Example 



done during the listing pass. Thus, the error message 
will appear in the listing file, but not on the screen 
during the actual assembly process. (.ERR2 has a 
different meaning with a two-pass assembler.) 

Again, since this is a single-pass assembler, this directive 
also generates a warning message so that you know if s 
pass-dependent and may not work as you expect. 

.ERRl 

.ERR2 /this will only appear in the listing file 



.ERRB 



Function 
Mode 
Syntax 
Remarks 



Forces an error if argument is blank 
MASM 

.ERRB <argument> 

You always use this argument inside a macro. It tests 
whether the macro was called with a real argument to 
replace the specified dummy argument. If the argument is 
blank (empty), an error message occurs on the source 
Une where the macro was invoked. 

You must always surround the argument to be tested 
with angle brackets (< >). 



See also 
Example 


.ERRNB 

DOUBLE MACRO ARGl 

.ERRB <ARG1> /require an argument 
shl ARG1,1 /double the argument's 

ENDM 


value 


.ERRDEF 


Function 
Mode 
Syntax 
Remarks 


Forces an error if a symbol is defined 
MASM 

.ERRDEF symbol 

.ERRDEF causes an error message to be c 


generated at the 



current source line number if symbol has already been 
defined in your source file. 
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See also 
Example 



.ERRNDEF 

SetMode MACRO ModeVal 
.ERRDEF _MODE 

_MODE EQU ModeVal 
ENDM 



; error if already defined 



.ERRDIF 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Forces an error if arguments are different 
MASM 

.ERRDIF <argumentl> ,<argument2> 

You always use .ERRDIF inside a macro. It tests 
whether its two arguments are identical character 
strings. If the two strings are not identical, an error mes- 
sage occurs on the source line where the macro was 
invoked. The two strings are compared on a character- 
by-character basis; case is significant. If you want case to 
be ignored, use the .ERRDIFI directive. 

You must always surround each argument in angle 
brackets (< >); separate arguments with a comma. 

.ERRIDN, .ERRDIFI, .ERRIDNI 



SegLoad MACRO reg,val 
.ERRDIF <reg>,<es> 
mov ax,val 
mov reg,ax 

ENDM 



;only permit ES register 



.ERRDIFI 



Function 
Mode 
Syntax 
Remarks 



Forces an error if arguments are different, ignoring case 
MASM 

.ERRDIFI <argumentl>,<argment2> 

You always use .ERRDIFI inside a macro. It tests 
whether its two arguments are identical character 
strings. If the two strings are not identical, an error mes- 
sage occurs on the source line where the macro was 
invoked. The two strings are compared on a character- 
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See also 
Example 



by-character basis; case is insignificant. If you want case 
to be significant, use the .ERRDIF directive. 

You must always surround each argument in angle 
brackets (< >); separate arguments with a comma. 

.ERRIDN, .ERRDIF, .ERRIDNI 



SegLoad MACRO reg,val 
.ERRDIF <reg>,<es> 
mov ax,val 
mov reg,ax 
ENDM 



;only permit ES register 
/•works no matter how reg typed 



.ERRE 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Forces an error if expression is false (0) 
MASM 

.ERRE expression 

expression must evaluate to a constant and cannot 
contain any forward-referenced symbol names. If the 
expression evaluates to 0, an error message occurs at the 
current source line. 

.ERRNZ 



PtrLoad MACRO PTR,val 
.ERRE val 
mov si, val 

ENDM 



; error if attempt load to pointer 



.ERRIDN 



Function 
Mode 
Syntax 
Remarks 



Forces an error if arguments are identical 
MASM 

.ERRIDN <argumentl>,<argument2> 

You always use .ERRIDN inside a macro. It tests 
whether its two arguments are identical character 
strings. If the two strings are identical, an error message 
occurs on the source line where the macro was invoked. 
The two strings are compared on a character-by- 
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See also 
Example 



character basis; case is significant. If you want case to be 
ignored, use the .ERRIDNI directive. 

You must always surround each argument in angle 
brackets (< >); separate arguments with a comma. 

.ERRDIF, .ERRIDNI, .ERRDIFI 

PushSeg MACRO reg,val 



•ERRIDN <reg>,<cs> 
push reg 
mov reg,val 
ENDM 



;CS load is illegal 



.ERRIDNI 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Forces an error if arguments are identical, ignoring case 
MASM 

.ERRIDNI <argumentl>,<argume/it2> 

You always use .ERRIDNI inside a macro. It tests 
whether its two arguments are identical character 
strings. If the two strings are identical, an error message 
occurs on the source line where the macro was invoked. 
The two strings are compared on a character-by- 
character basis; case is insignificant. If you want case to 
be significant, use the .ERRIDN directive. 

You must always surround each argument in angle 
brackets (< >); separate arguments with a comma. 

.ERRDIF, .ERRIDN, .ERRDIFI 



PushSeg MACRO reg,val 
.ERRIDNI <reg>,<cs> 
push reg 
mov reg,val 

ENDM 



;CS load is illegal 
; takes CS or cs 
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ERRIF 



Function 
Mode 
See also 



Forces an error if expression is true (nonzero) 
MASM, Ideal 
.ERRE, .ERRNZ 



ERRIFl 



Function 
Mode 
See also 



Forces an error message on pass 2 

MASM, Ideal 

.ERRl 



ERRIF2 



Function 
Mode 
See also 



Forces an error message on pass 2 

MASM, Ideal 

.ERR2 



ERRIFB 



Function 
Mode 
See also 



Forces an error if argument is blank 

MASM, Ideal 

.ERRB 



ERRIFDEF 



Function 
Mode 
See also 



Forces an error if a symbol is defined 

MASM, Ideal 

.ERRDEF 
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ERRIFDIF 


Function 


Forces an error if arguments are different 


Mode 


MASM, Ideal 


See also 


.ERRDIF 


ERRIFDIFI 


Function 


Forces an error if arguments are different, ignoring case 


Mode 


MASM, Ideal 


See also 


.ERRDIFI 


ERRIFE 


Function 


Forces an error if expression is false (0) 


Mode 


MASM, Ideal 


See also 


.ERRE 


ERRIFIDN 


Function 


Forces an error if arguments are identical 


Mode 


MASM, Ideal 


See also 


.ERRIDN 


ERRIFIDNI 


Function 


Forces an error if arguments are identical, ignoring case 


Mode 


MASM, Ideal 


See also 


.ERRIDNI 
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ERRIFNB 


Function 


Forces an error if argument is not blank 


Mode 


MASM, Ideal 


See also 


.ERRNB 


ERRIFNDEF 


Function 


Forces an error if symbol is not defined 


Mode 


MASM, Ideal 


See also 


.ERRNDEF 


•ERRNB 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Forces an error if argument is not blank 
MASM 

.ERRNB <argument> 

You always use .ERRNB inside a macro. It tests whether 
the macro was called with a real argument to replace the 
specified dummy argument. If the argument is not blank, 
an error message occurs on the source line where the 
macro was invoked. 

You must always surround the argument to be tested 
with angle brackets (< >). 

.ERRB 



Dolt MACRO a,b 
.ERRNB <B> 

ENDM 



;only need one argument 
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.ERRNDEF 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Forces an error if symbol is not defined 
MASM 

.ERRNDEF symbol 

.ERRNDEF causes an error message to be generated at 
the current source line number if symbol has not yet been 
defined in your source file. The error occurs even if the 
symbol is defined later in the file (forward-referenced). 



.ERRDEF 

.ERRNDEF BufSize 
BUF DB BufSize 



;no buffer size set 



.ERRNZ 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Forces an error if expression is true (nonzero) 
MASM 

.ERRNZ expression 

expression must evaluate to a constant and may not 
contain any forward-referenced symbol names. If the 
expression evaluates to a nonzero value, an error mes- 
sage occurs at the current source line. 

.ERRE 

.ERRNZ $ GT lOOOh /segment too big 



EVEN 



Function 
Mode 
Syntax 
Remarks 



Rounds up the location counter to the next even address 
MASM, Ideal 



EVEN 



EVEN allows you to align code for efficient access by 
processors that use a 16-bit data bus (8086, 80186, 80286). 
It does not improve performance for those processors 
with an 8-bit data bus (8088, 80188). 
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See also 
Example 



You can't use this directive in a segment that has BYTE- 
alignment, as specified in the SEGMENT directive that 
opened the segment. 

If the location counter is odd when an EVEN directive 
appears, a single byte of a NOP instruction is inserted in 
the segment to make the location counter even. By 
padding with a NOP, EVEN can be used in code 
segments without causing erroneous instructions to be 
executed at run time. If the location is already even, this 
directive has no effect. A warning is generated for the 
EVEN directive if alignment is not strict enough. 

ALIGN, EVENDATA 



;align for efficient access 



@@A: 


lodsb 






xor 


bl,al 




loop 


@@A 



EVENDATA 



Function 

Mode 

Syntax 

Remarks 



See also 



Rounds up the location counter to the next even address 
in a data segment 

Masm, Ideal 

EVENDATA 

EVENDATA allows you to align data for efficient access 
by processors that use a 16-bit data bus (8086, 80186, 
80286). It does not improve performance for those 
processors with an 8-bit data bus (8088, 80188). 
EVENDATA even-aligns by advancing the location 
counter without emitting data, which is useful for 
uninitialized segments. A warning is generated if the 
alignment isn't strict enough. 

You can't use this directive in a segment that has BYTE- 
alignment, as specified in the SEGMENT directive that 
opened the segment. 

If the location counter is odd when an EVENDATA 
directive appears, a single byte of is inserted in the 
segment to make the location counter even. If the loca- 
tion is already even, this directive has no effect. 

ALIGN, EVEN 
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Example 



EVENDATA 
VARl DW 



/align for efficient 8086 access 



EXITM 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Terminates macro- or block-repeat expansion 
MASM, Ideal 

EXITM 

EXITM stops any macro expansion or repeat block 
expansion that's in progress. All remaining statements 
after the EXITM are ignored. 

This is convenient for exiting from multiple levels of 
conditional assembly. 

ENDM, IRP, IRPC, REPT, MACRO 

Shiftn MACRO OP,N 
Count - 

REPT N 

shl OP,N 
Count = Count + 1 

IF Count GE 8 ;no more than 8 allowed 
EXITM 

ENDIF 

ENDM 



EXTRN 



Function 
Mode 
Syntax 
Remarks 



Indicates a symbol is defined in another module 
MASM, Ideal 

EXTRN definition [, definition]... 

Each definition describes a symbol and has the following 
format: 

name: type [: count] 

name is the symbol that is defined in another module. 
type must match the type of the symbol where it's 
defined in another module. It can be one of the 
following: 
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■ NEAR, FAR, or PROC. PROC is either NEAR or FAR 
(depending on the memory model set using the 
MODEL directive) 

B BYTE, WORD, DWORD, DATAPTR, FWORD, 
PWORD, QWORD, TBYTE, or a structure name 

■ ABS 

The optional count specifies how many items this 
external symbol defines. If the symbol's definition in 
another file uses the DUP directive to allocate more than 
one item, you can place that value in the count field. 
This lets the SIZE and LENGTH operators correctly 
determine the size of the external data item. If you do 
not specify a count, it is assumed to be one. 

You can define more than one external symbol by 
separating each definition with a comma (,). Also, each 
argument of EXTRN accepts the same syntax as an 
argument of ARG or LOCAL. 

name must be declared as PUBLIC in another module in 
order for your program to link correctly. 

You can use the EXTRN directive either inside or 
outside a segment declared with the SEGMENT 
directive. If you place EXTRN inside a segment, you are 
informing the assembler that the external variable is in 
another module but in the same segment. If you place 
the EXTRN directive outside of any segment, you are 
informing the assembler that you do not know which 
segment the variable is declared in. 

In MASM mode, external symbols declared outside of 
any segment are presumed to be reachable via the DS 
register, which may not always be a valid assumption. 
Make sure that you either place the correct segment 
value in DS, or use an explicit segment override when 
referring to these variables. 

In Ideal mode. Turbo Assembler correctly checks for 
whether the external variable is addressable using any 
of the current segment registers, as described with the 
ASSUME directive. 

See also COMM, GLOBAL, PUBLIC 

Example extrn aproc:NEAR 

call APROC /calls into other module 
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.FARDATA 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Defines the start of a far data segment 
MASM 

.FARDATA [name] 

.FARDATA indicates the start of a far initialized data 
segment. If you wish to have multiple, separate far data 
segments, you can provide an optional name to override 
the default segment name, thereby making a new 
segment. 

You can place as many .FARDATA directives as you 
want in a source file. All the different pieces with the 
same name will be combined to produce one data 
segment, exactly as if you had entered all the data at 
once after a single .FARDATA directive. 

Far data segments are not put in a group. You must 
explicitly make far segments accessible by loading the 
address of the far segment into a segment register before 
accessing the data. 

See the .MODEL directive for complete information on 
the segment attributes for far data segments. 

.FARDATA?, .CODE, .DATA, .MODEL, .STACK 

.FARDATA 

FarBuf DB 80 DUP (0) 

.CODE 

mov ax,@fardata 

mov ds,ax 

ASSUME ds:@fardata 

mov al, FarBuf [0] ;get first byte of buffer 



.FARDATA? 



Function 
Mode 
Syntax 
Remarks 



Defines the start of a far uninitialized data segment 
MASM 

.FARDATA? [name] 

.FARDATA? indicates the start of a far uninitialized 
data segment. If you wish to have multiple separate far 
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See also 
Example 



data segments, you can provide an optional name to 
override the default segment name, thereby making a 
new segment. 

You can place as many .FARDATA? directives as you 
want in a source file. All the different pieces with the 
same name will be combined to produce one data seg- 
ment, exactly as if you had entered all the data at once 
after a single .FARDATA? directive. 

Far data segments are not put in a group. You must 
explicitly make far segments accessible by loading the 
address of the far segment into a segment register before 
accessing the data. 

See the .MODEL directive for complete information on 
the segment attributes for uninitialized far data 
segments. 

.CODE , .DATA, .FARDATA, .MODEL, .STACK 

.FARDATA? 

FarBuf DB 80 DUP (?) 

.CODE 

mov ax,@fardata? 

mov ds,ax 

ASSUME dsrGfardata? 

mov al, FarBuf [0] ;get first byte of buffer 



FARDATA 



Function 
Mode 
Syntax 
Remarks 
See also 



Defines the start of a far data segment 
MASM, Ideal 

FARDATA [name] 

Same as .FARDATA. 

.FARDATA 
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GLOBAL 

Function 
Mode 
Syntax 
Remarks 



Defines a global symbol 
MASM, Ideal 

GLOBAL definition [,definition] .. . 

GLOBAL acts as a combination of the EXTRN and 
PUBLIC directives. Each definition describes a symbol 
and has the following format: 

name:type [: count] 

If name is defined in the current source file, it is made 
public exactly as if used in a PUBLIC directive. If name is 
not defined in the current source file, it is declared as an 
external symbol of type h/pe, as if the EXTRN directive 
had been used. 

type must match the type of the symbol in the module 
where it is defined. It can be one of the following: 

■ NEAR, FAR, or PROC 

■ BYTE, WORD, DATAPTR, DWORD, FWORD, 
PWORD, QWORD, TBYTE, or a structure name 

■ ABS 

The optional count specifies how many items this 
symbol defines. If the symbol's definition uses the DUP 
directive to allocate more than one item, you can place 
that value in the count field. This lets the SIZE and 
LENGTH operators correctly determine the size of the 
external data item. If you do not specify a count, it is 
assumed to be one. 

The GLOBAL directive lets you have an INCLUDE file 
included by all source files; the INCLUDE file contains 
all shared data defined as global symbols. When you 
reference these data items in each module, the GLOBAL 
definition acts as an EXTRN directive, describing how 
the data is defined in another module. In the module in 
which you define the data item, the GLOBAL definition 
acts as a PUBLIC directive, making the data available to 
the other modules. 

You can define more than one public symbol by 
separating each definition with a comma (,). 
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You must define a symbol as GLOBAL before you first 
use it elsewhere in your source file. Also note that each 
argument of GLOBAL accepts the same syntax as an 
argument of EXTRN, ARG, or LOCAL. 

Note: In QUIRKS mode, the GLOBAL directive can be 
overridden. For example, 

global DB ? 

is a legal declaration under QUIRKS, though a warning 
will be generated. 

COMM, EXTRN, PUBLIC 



GLOBAL X:WORD,Y:BYTE 
X DW 
mov al,Y 



;made public for other module 
;Y is defined as external 



GROUP 



Function 

Mode 
Syntax 



Remarks 



Defines segments as accessible from a single segment 
register 

MASM, Ideal 

MASM mode: 

name GROUP segmentname [ , segmentname] . . . 
Ideal mode: 

GROUP name segmentname [, segment name] .. . 

name defines the name of the group, segmentname can be 
either a segment name defined previously with the 
SEGMENT directive or an expression starting with 
SEG. You can use name in the ASSUME directive and 
also as a constant in expressions, where it evaluates to 
the starting paragraph address of the group. 

All the segments in a group must fit into 64K, even 
though they don't have to be contiguous when linked. 

In MASM mode, you must use a group override 
whenever you access a symbol in a segment that is part 
of a group. In Ideal mode. Turbo Assembler auto- 
matically generates group overrides for symbols in 
segments that belong to a group. 

In the example shown here, even though varl and var2 
belong to different segments, they both belong to the 
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See also 
Example 



group D GROUP. Once the DS segment register is set to 
the base address of D GROUP, varl and varl can be 
accessed as belonging in a single segment. 

Notice that in Ideal mode, the name comes after the 
GROUP directive. 

SEGMENT, ASSUME 



DGROUP GROUP SEG1,SEG2 

SEGl SEGMENT 

VARl DW 3 

SEGl ENDS 

SEG2 SEGMENT 

VAR2 DW 5 

SEG2 ENDS 

SEG3 SEGMENT 

mov ax, DGROUP 

mov ds,ax 

ASSUME DS: DGROUP 

mov ax, VARl 

mul VAR2 

SEG3 ENDS 



;get base address of group 
;set up to access data 
/inform assembler of DS 



IDEAL 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Enters Ideal assembly mode 
MASM, Ideal 

IDEAL 

IDEAL makes the expression parser only accept the 
more rigid, type-checked syntax required by Ideal mode. 
See Chapter 12 of the User's Guide for a complete 
discussion of the capabilities and advantages of Ideal 
mode. 

Ideal mode will stay in effect until it is overridden by a 
MASM or QUIRKS directive. 

QUIRKS, MASM 

IDEAL 
mov [BYTE ds:si],l ;Ideal operand syntax 
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IF 



Function 

Mode 

Syntax 

Remarks 



See also 
Example 



Starts conditional assembly block; enabled if expression 
is true 

MASM, Ideal 

IF expression 

expression must evaluate to a constant and may not 
contain any forward-referenced symbol names. If the 
expression evaluates to a nonzero value, the statements 
within the conditional block are assembled. 

Use the ENDIF directive to terminate the conditional 
assembly block. 

ENDIF, ELSE, IFl, IF2, IFB, IFDEF, IFDIF, IFDIFI, IFE, 
IFIDN, IFIDNI, IFNB, IFNDEF 

IF DoBuffering 

mov ax,BufNum 

call ReadBuf 
ENDIF 



IFl 



Function 
Mode 
Syntax 
Remarks 



Starts conditional assembly block; enabled on pass 1 
MASM, Ideal 

IFl 

Because Turbo Assembler is a single-pass assembler, the 
statements within the conditional block are assembled 
on the assembly pass, but not during any subsequent 
listing pass. (IFl has a different meaning with a two- 
pass assembler.) 

When using a forward-referenced operator redefinition, 
you can't always tell from the listing file that something 
has gone wrong. By the time the listing is generated on 
pass 2, the operator has been redefined. This means that 
the listing wiU appear to be correct, but the code would 
not have been generated properly to the object file. 

Use the ENDIF directive to terminate the conditional 
assembly block. 
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See also 
Example 



ELSE, ENDIF, IF, IF2, IFB, IFDEF, IFDIF, IFDIFI, IFE, 
IFIDN, IFIDNI, IFNB, IFNDEF 

IFl 

;This line doesn't appear in listing 
ENDIF 



IF2 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Starts conditional assembly block; enabled on pass 2 
MASM, Ideal 

IF2 

Because Turbo Assembler is a single-pass assembler, the 
statements within the conditional block are assembled 
on the listing pass, but not during the previous assembly 
pass. (IF2 has a different meaning with a two-pass 
assembler.) 

Because Turbo Assembler is a single-pass assembler, IF2 
also generates a warning message to inform you that it is 
pass-dependent and may not work as you'd expect. 

When using a forward-referenced operator redefinition, 
you can't always teU from the listing file that something 
has gone wrong. By the time the listing is generated on 
pass 2, the operator has been redefined. This means that 
the listing will appear to be correct, but the code would 
not have been generated properly to the object file. 

Use the ENDIF directive to terminate the conditional 
assembly block. 

ELSE, ENDIF, IF, IFl, IFB, IFDEF, IFDIF, IFDIFI, IFE, 
IFIDN, IFIDNI, IFNB, IFNDEF 

IF2 
;Only appears in listing 

ENDIF 
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IFB 



Function 

Mode 

Syntax 

Remarks 



See also 
Example 



Starts conditional assembly block; enabled if argument 
is blank 

MASM, Ideal 

IFB <argument> 

If argument is blank (empty), the statements within the 
conditional block are assembled. Use IFB to test whether 
a macro was called with a real argument to replace the 
specified dummy argument. 

You must always surround the argument to be tested 
with angle brackets (< >). 

Use the ENDIF directive to terminate the conditional 
assembly block. 

ELSE, ENDIF, IF, IFl, IF2, IFDEF, IFDIF, IFDIFI, IFE, 
IFIDN, IFIDNI, IFNB, IFNDEF 

PRINT MACRO MSG 
IFB <MSG> 
mov si,DefaultMsg 
ELSE 

mov si, MSG 
ENDIF 

call Showit 
ENDM 



IFDEF 



Function 

Mode 

Syntax 

Remarks 



See also 



Starts conditional assembly block; enabled if symbol is 
defined 

MASM, Ideal 

IFDEF symbol 

U symbol is defined, the statements within the condi- 
tional block are assembled. 

Use the ENDIF directive to terminate the conditional 
assembly block. 

ELSE, ENDIF,IF, IFl, IF2, IFB, IFDIF, IFDIFI, IFE, 
IFIDN, IFIDNI, IFNB, IFNDEF 
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Example 



IFDEF SaveSize 
BUF DB SaveSize DUP (?) 

ENDIF 



; define BUFFER only if 
; SAVESIZE is defined 



IFDIF, IFDIFI 



Function 

Mode 

Syntax 

Remarks 



See also 
Example 



Starts conditional assembly block; enabled if arguments 
are different 

MASM, Ideal 

IFDIF <argumentl>,<argument2> 

You usually use IFDIF inside a macro. It tests whether 
its two arguments are different character strings. Either 
of the arguments can be macro dummy arguments that 
will have real arguments to the macro call that was 
substituted before performing the comparison. If the 
two strings are different, the statements within the 
conditional block are assembled. The two strings are 
compared on a character-by-character basis; case is 
significant. If you want case to be ignored, use the 
IFDIFI directive. 

Use the ENDIF directive to terminate the conditional 
assembly block. 

ELSE, ENDIF, IF, IFl, IF2, IFB, IFDEF, IFDIFI, IFE, 
IFIDN, IFIDNI, IFNB, IFNDEF 



loadb MACRO source 
IFDIF <source>,<si> 

mov si, source 
ENDIF 
lodsb 
ENDM 



;set up string pointer 
;read the byte 



IFE 



Function 

Mode 
Syntax 



Starts conditional assembly block; enabled if expression is 
false 

MASM, Ideal 

IFE expression 
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Remarks 



See also 
Example 



expression must evaluate to a constant and may not 
contain any forward-referenced symbol names. If the 
expression evaluates to zero, the statements within the 
conditional block are assembled. 

Use the ENDIF directive to terminate the conditional 
assembly block. 

ELSE, ENDIF, IF, IFl, IF2, IFB, IFDEF, IFDIF, IFDIFI, 
IFIDN, IFIDNI, IFNB, IFNDEF 



IFE StackSize 
StackSize=1024 

DB StackSize DUP (?) 
ENDIF 



/allocate stack 



IFIDN, IFIDNI 



Function 

Mode 

Syntax 

Remarks 



See also 
Example 



Starts conditional assembly block; enabled if arguments 
are identical 

MASM, Ideal 

IFIDN <argumentl>,<argument2> 

You usually use IFIDN inside a macro. It tests whether 
its two arguments are identical character strings. Either 
of the arguments can be macro dummy arguments that 
will have real arguments to the macro call that was 
substituted before performing the comparison. If the 
two strings are identical, the statements within the 
conditional block are assembled. The two strings are 
compared on a character-by-character basis; case is 
significant. If you want case to be ignored, use the 
IFIDNI directive. 

Use the ENDIF directive to terminate the conditional 
assembly block. 

ELSE, ENDIF, IF, IFl, IF2, IFB, IFDEF, IFDIF, IFDIFI, 
IFE, IFIDNI, IFNB, IFNDEF 

RDWR MACRO BUF,RWMODE 
mov ax,BUF 
IFIDN <RWMODE>,<READ> 

call ReadIt 
ENDIF 
IFIDN <RWMODE>,<WRITE> 

call Writelt 
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ENDIF 
ENDM 



IFNB 



Function 

Mode 

Syntax 

Remarks 



See also 
Example 



Starts conditional assembly block, enabled if argument 
is nonblank 

MASM, Ideal 

IFNB <argume/it> 

l( argument is nonblank, the statements within the condi- 
tional block are assembled. Use IFNB to test whether a 
macro was called with a real argument to replace the 
specified dummy argument. 

You must always surround the argument to be tested 
with angle brackets (< >). 

Use the ENDIF directive to terminate the conditional 
assembly block. 

ELSE, ENDIF, IF, IFl, IF2, IFB, IFDEF, IFDIF, IFDIH, 
IFE, IFIDN, IFIDNI, IFNDEF 

PopRegs MACRO REG1,REG2 
IFNB <REG1> 

pop REGl 
ENDIF 
IFNB <REG2> 

pop REG2 
ENDIF 
ENDM 



IFNDEF 



Function 

Mode 

Syntax 

Remarks 



Starts conditional assembly block; enabled if symbol is 
not defined 

MASM, Ideal 

IFNDEF symbol 

If symbol has not yet been defined in the source file, the 
statements within the conditional block are assembled. 

Use the ENDIF directive to terminate the conditional 
assembly block. 
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See also 
Example 



ELSE, ENDIF,IF, IFl, IF2, IFB, IFDEF, IFDIF, IFDIFI, 
IFE, IFIDN, IFIDNI, IFNB 



IFNDEF BufSize 
BufSize EQU 128 
ENDIF 



/•define buffer size if not defined 



%INCL 



Function 
Mode 
Syntax 
Remarks 

See also 
Example 



Allows listing of include files 
MASM, Ideal 

%INCL 

Use %INCL after a %NOINCL directive has turned off 
listing of INCLUDE files. This is the default INCLUDE 
file listing mode. 

%NOINCL 



%INCL 

INCLUDE DEFS.INC 



/•contents appear in listing 



INCLUDE 



Function 

Mode 

Syntax 



Remarks 



Includes source code from another file 
MASM, Ideal 

MASM mode: 

INCLUDE filename 

Ideal mode: 

INCLUDE "filename" 

filename is a source file containing assembler statements. 
Turbo Assembler assembles all statements in the 
included file before continuing to assemble the current 
file. 

filename uses the normal DOS file-naming conventions, 
where you can enter an optional drive, optional direc- 
tory, file name, and optional extension. If you don't 
provide an extension, .ASM is presumed. 

If filename does not include a directory or drive name. 
Turbo Debugger first searches for the file in any direc- 
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Example 



tories specified by the /I command-line option and then 
in the current directory. 

You can nest INCLUDE directives as deep as you want. 

Notice that in Ideal mode, you must surround the file- 
name with quotes. 



;MASM mode 
INCLUDE MYMACS.INC 
/•Ideal mode 
INCLUDE "DEFS.INC" 



/•include MACRO definitions 
/•include EQU definitions 



INCLUDELIB 



Function 


Tells the linker to include a library 


Mode 


MASM, Ideal 


Syntax 


MASM mode: 




INCLUDELIB filename 




Ideal mode: 




INCLUDELIB "filename" 



Remarks 



Example 



filename is the name of the library that you want the 
linker to include at link time. If you don't supply an 
extension with filename, the linker assumes .LIB. 

Use INCLUDELIB when you know that the source file 
will always need to use routines in the specified library. 
That way you don't have to remember to specify the 
library name in the linker commands. 

Notice that in Ideal mode, you must surround the file- 
name with quotes. 

INCLUDELIB diskio /includes DISKIO.LIB 



INSTR 



Function 
Mode 
Syntax 
Remarks 



Returns the position of one string inside another string 
MASM51, Ideal 

name INSTR [start,] stringl,sti:ing2 

name is assigned a value that is the position of the first 
instance o{ string! in stringl. The first character in stringl 
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has a position of one. If string! does not appear any- 
where within stringl, a value of is returned. 

CATSTR, SIZESTR, SUBSTR 

COMMPOS INSTR <aaa,bbb>,<,> ;COMMAPOS = 4 



IRP 



Function 

Mode 

Syntax 

Remarks 



See also 
Example 



Repeats a block of statements with string substitution 
MASM, Ideal 

IRP parameter, <argl [ , arg2] . , . > 

statements 
ENDM 

The statements within the repeat block are assembled 
once for each argument in the list enclosed in angle 
brackets. The list may contain as many arguments as 
you want. The arguments may be any text, such as 
symbols, strings, numbers, and so on. Each time the 
block is assembled, the next argument in the list is 
substituted for any instance of parameter in the enclosed 
statements. 

You must always surroimd the argument list with angle 
brackets (< >), and arguments must be separated by 
commas. Use the ENDM directive to end the repeat 
block. 

You can use IRP both inside and outside of macros. 

IRPC, REFT 

IRP reg,<ax,bx,cx,dx> 
push reg 

ENDM 



IRPC 



Function 

Mode 

Syntax 



Repeats a block of statements with character substitution 
MASM, Ideal 



IRPC parameter, string 
statements 

ENDM 
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in 



Remarks 



See also 
Example 



The statements within the repeat block are assembled 
once for each character in string. The string may contain 
as many characters as you want. Each time the block is 
assembled, the next character in the Ust is substituted for 
any instances of parameter in the enclosed statements. 

Use the ENDM directive to end the repeat block. 

You can use IRPC both inside and outside of macros. 



IRP, REPT 

IRPC LUCKY, 1379 

DB LUCKY 
ENDM 



/allocate a lucky number 



This creates 4 bytes of data containing the values 1, 3, 7, 
and 9. 



JUMPS 



Function 

Mode 

Syntax 

Remarks 



Enables stretching of conditional jumps to near or far 
addresses 

MASM, Ideal 

JUMPS 

JUMPS causes Turbo Assembler to look at the 
destination address of a conditional jump instruction, 
and if it is too far away to reach with the short 
displacement that these instructions use, it generates a 
conditional jump of the opposite sense around an 
ordinary jump instruction to the desired target address. 
For example, 

jne xyz 

becomes 

je @@A 
jmp xyz 
@@a: 

If the destination address is forward-referenced, you 
should use the NEAR or FAR operator to tell Turbo 
Assembler how much space to allocate for the jump 
instruction. If you don't do this, inefficient code may be 
generated. 
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This directive has the same effect as using the /JJUMPS 
command-line option. 



See also 


NOJUMPS 




Example 


JUMPS 


/enable jump stretching 




jne SHORT @A 


;can reach A 




@@A: 





LABEL 



Function 

Mode 

Syntax 



Remarks 



See also 
Example 



Defines a symbol with a specified type 
MASM, Ideal 

MASM mode: 

name LABEL type 

Ideal mode: 

LABEL name type 

name is a sjonbol that you have not previously defined 
in the source file, type describes the size of the symbol 
and whether it refers to code or data. It can be one of the 
following: 

■ NEAR, FAR, or PROC. PROC is the same as either 
NEAR or FAR, depending on the memory set using 
the MODEL directive 

■ BYTE, WORD, DATAPTR, DWORD, FWORD, 
PWORD, QWORD, TBYTE, or a structure name 

The label will only be accessible from within the current 
source file, unless you use the PUBLIC directive to make 
it accessible from other source files. 

Notice that in Ideal mode, name comes after the LABEL 
directive. 

Use LABEL to access different-sized items than those in 
the data structure; see the example that follows. 



WORDS LABEL WORD 
BYTES DB 64 DUP (0) 
mov WORDS [2], 1 



/access "BYTES" as WORDS 
;write WORD of 1 
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.LALL 



Function 


Enables listing of macro expansions 


Mode 


MASM 


Syntax 


.LALL 


See also 


%MACS 



.LFCOND 



Function 
Mode 
Syntax 
Remarks 

See also 



Shows aU statements in conditional blocks in the listing 
MASM 

.LFCOND 

.LFCOND enables the listing of false conditional blocks 
in assembly listings. .LFCOND is not affected by the /X 
option. 

%CONDS 



%LINUM 



Function 
Mode 
Syntax 
Remarks 



Example 



Sets the width of the line-number field in listing file 
MASM, Ideal 

%LINUM size 

%LINUM allows you to set how many columns the line 
numbers take up in the listing file, size must be a 
constant. If you want to make your listing as narrow as 
possible, you can reduce the width of this field. Also, if 
your source file contains more than 9,999 lines, you can 
increase the width of this field so that the line numbers 
are not truncated. 

The default width for this field is 4 columns. 



%LINUM 5 



/allows up to line 99999 
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%LIST 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Shows source lines in the listing 
MASM, Ideal 

%LIST 

%LIST reverses the effect of a %NOLIST directive that 
caused all listing output to be suspended. 

This is the default listing mode; normally, all source 
lines are placed in the listing output file. 

.LIST, %NOLIST, .XLIST 



%LIST 
jmp xyz 



;this line always listed 



•LIST 



Function 


Shows source lines in the listing 


Mode 


MASM 


Syntax 


.LIST 


See also 


%LIST 


Example 


.XLIST ;turn off list: 



INCLUDE MORE. INC 

.LIST ;turn on listing 



LOCAL 



Function 

Mode 

Syntax 



Remarks 



Defines local variables for macros and procedures 
MASM, Ideal 
In macros: 

LOCAL symbol [, symbol] . . . 

In procedures: 

LOCAL /lame; type [: count] [, name :typel: count] ] ... [=symbol] 

LOCAL can be used both inside macro definitions 
started with the MACRO directive and within proce- 
dures defined with PROC. It behaves slightly differently 
depending on where it is used. 
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Within a macro definition, LOCAL defines temporary 
symbol names that are replaced by new unique symbol 
names each time the macro is expanded. The unique 
names take the form of ?? number, where number is 
hexadecimal and starts at 0000 and goes up to FFFF. 

Within a procedure, LOCAL defines names that access 
stack locations as negative offsets relative to the BP 
register. The first local variable starts at BP (type X 
count). If you end the argument list with an equal sign 
(=) and a symbol, that symbol will be equated to the 
total size of the local symbol block in bytes. You can then 
use this value to make room on the stack for the local 
variables. 

Each localdef has the following syntax: 

localname:[ [distance] PTR] type [: count] 
You can use this alternative syntax for each localdef: 

localname[ [count] ][: [distance] PTR] type] 

localname is the name you'll use to refer to this local 
symbol throughout the procedure. 

type is the data type of the argument and can be one of 
the following: WORD, DATAPTR, DWORD, FWORD, 
PWORD, QWORD, TBYTE, or a structure name. If you 
don't specify a type, and you're using the alternative 
syntax, WORD size is assumed. 

count specifies how many elements of the specified type 
to allocate on the stack. 

The optional distance and PTR lets you tell Turbo 
Assembler to include debugging information for Turbo 
Debugger, which tells it this local variable is really a 
pointer to another data tj^. See the PROC directive for 
a discussion of how this works. 

Here are some examples of valid arguments: 

LOCAL X : DWORD: 4, Y: NEAR PTR WORD 

Here are some arguments using the alternative syntax: 

LOCAL X[4]:DW0RD,Y:PTR STRUCNAME 

The type indicates how much space should be reserved 
for name. It can be one of BYTE, WORD, DATAPTR, 
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See also 
Example 



DWORD, FWORD, PWORD, QWORD, or TBYTE for a 

data value. It can be one of NEAR, FAR, or FROC for a 
code pointer. 

The LOCAL directive must come before any other 
statements in a macro definition. It can appear anyrvhere 
within a procedure, but should precede the first use of 
the symbol it defines. 

ARC, MACRO, FROC, USES 



OnCarry MACRO FUNC 

LOCAL DONE 

jnc DONE 

call FUNC 
DONE: 

ENDM 
READ PROC NEAR 

LOCAL N:WORD =LSIZE 

push bp 

mov bp, sp 

sub sp,LSIZE 

mov N, 

;Body of func goes here 

add sp,LSIZE 

pop bp 

ret 
READ ENDP 



;hop around if no carry 
/•else call function 



;make room for local var 
/actually N = [BP-2] 

/adjust stack 



LOCALS 



Function 
Mode 
Syntax 
Remarks 



Enables local symbols 
MASM, Ideal 

LOCALS [prefix] 

Local symbols normally start with two at-signs 
which is the default, and are only visible inside blocks 
whose boundaries are defined by the FROC/ENDP pair 
within a procedure or by nonlocal symbols outside a 
procedure. You define a nonlocal symbol using FROC, 
LABEL, or the colon operator. If you use the LOCALS 
directive, any symbols between pairs of nonlocal 
symbols can only be accessed from within that block. 
This lets you reuse symbol names inside procedures and 
other blocks. 
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See also 
Example 



prefix is the two-character symbol prefix you want to use 
to start local symbol names. Usually, two at-signs 
indicate a local symbol. If you have a program that has 
symbols starting with two at-signs, or if you use your 
own convention to indicate local symbols, you can set 
two different characters for the start of local symbols. 
The two characters must be a valid start of a symbol 
name, for example .? is OK, but .. is not. When you set 
the prefix, local symbols are enabled at the same time. If 
you turn off local symbols with the NOLOCALS 
directive, the prefix is remembered for the next time you 
enable local symbols with the LOCALS directive. 

Local symbols are automatically enabled in Ideal mode. 
You can use the NOLOCALS directive to disable local 
symbols. Then, all subsequent symbol names will be 
accessible throughout your source file. 

NOLOCALS, IDEAL 



.MODEL 


small 


.CODE 




start: 




@@1: 


; 


loop 


e@i 


one: 


/ 


loop 


one 


@@1: 


/ 


loop 


@@1 


Foo 


PROG NEAR ; 


@@1: 


1 


loop 


@@1 


two: 


i 


loop 


two 


e@i: 


; 


loop 


@@1 


Foo 


ENDP 



unique label 

terminates visibility of @1 above 

unique label 

terminates visibility of @1 above 
unique label 

doesn't terminate visibility of @@1 
above because in PROCs local labels 
have visibility throughout the PROC 

conflicting label with @@1 above 



END 



start 
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MACRO 



Function 


Defines a macro 


Mode 


MASM, Ideal 


Syntax 


MASM mode: 




najjie MACRO [parameter [, parameter] .. .] 




Ideal mode: 




MACRO name [parameter [/parameter] .. .] 



Remarks 



See also 


ENDM 


Example 


SWAP MACRO a,b 




mov ax, a 




mov a,b 




mov b,ax 




ENDM 



You use name later in your source file to expand the 
macro, parameter is a placeholder you can use through- 
out the body of the macro definition wherever you want 
to substitute one of the actual arguments the macro is 
called with. 

Use the ENDM directive to end the macro definition. 



;swap two word items 



%MACS 



Function 
Mode 
Syntax 
Remarks 

See also 
Example 



Enables listing of macro expansions 
MASM, Ideal 

%MACS 

%MACS reverses the effect of a previous %NOMACS 
directive, so that the lines resulting from macro expan- 
sions appear in the listing. (Same as .LALL.) 

.LALL, %NOMACS, .SALL, .XALL 



%MACS 
MyMac 1,2,3 



;expansion appears in listing 
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MASM 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Enters MASM assembly mode 
MASM, Ideal 

MASM 

MASM tells the expression parser to accept MASM's 
loose expression syntax. See Appendix B for a discussion 
of how this differs from Ideal mode. 

Turbo Assembler is in MASM mode when it first starts 
assembling a source file. 

QUIRKS, IDEAL 



MASM 

mov al,es:24h 



;ghastly construct 



MASM51 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Enables assembly of some MASM 5.1 enhancements 
MASM, Ideal 

MASM51 

MASM51 enables the following capabilities that are not 
normally available with Turbo Assembler: 

■ SUBSTR, CATSTR, SIZESTR, and INSTR directives 

■ Line continuation with backslash (\) 

If you also enable Quirks mode with the QUIRKS 
directive, these additional features become available: 



■ Local labels defined with @@ and referred to with @F 
and@B 

■ Redefinition of variables inside PROCs 

■ Extended model PROCs are all PUBLIC. 

NOMASM51 

MASM51 

MyStr CATSTR <ABC>,<XYZ> ;MYSTR = "ABCXYZ" 
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.MODEL 

Function 

Mode 
Syntax 

Remarks 



Sets the memory model for simplified segmentation 
directives 

MASM 

.MODEL memorymodel [, language] 
.MODEL TPASCAL 

memorymodel is a model of tiny, small, medium, compact, 
large, or huge. The large and huge models use the same 
segment definitions, but the @DataSize predefined 
equate symbol is defined differently. (See the section 
"Other Simplified Segment Directives" in Chapter 4 of 
the User's Guide for a description of the @DataSize 
symbol.) 

When you want to write an assembler module that 
interfaces to Turbo Pascal, you use a special form of the 
.MODEL directive: 

.MODEL TPASCAL 

This informs Turbo Assembler to use the Turbo Pascal 
segment-naming conventions. You can only use the 
.CODE and .DATA simplified segmentation directives 
when you specify TPASCAL. There is no need to supply 
a second argument to the .MODEL directive, TPASCAL 
says it all. If you try and use any of the directives that 
are forbidden with Turbo Pascal assembler modules, 
you will get a warning message. 

To define memorymodel, you must use the .MODEL 
directive before any other simplified segmentation 
directives such as .CODE, .DATA, .STACK, and so on. 
The code and data segments will all be 32-bit segments if 
you've enabled the 80386 processor with the .386 or 
.386P directive before issuing the .MODEL directive. Be 
certain this is what you want before you implement it. 
Also be sure to put the .MODEL directive before either 
.386 or .386P if you want 16-bit segments. 

language tells Turbo Assembler what language you will 
be calling from to access the procedures in this module. 
language can be C, Pascal, Basic, FORTRAN, or Prolog. 
Turbo Assembler automatically generates the appro- 
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priate procedure entry and exit code when you use the 
PROC and ENDP directives. 

If you specify the C language, all public and external 
symbol names wUl be prefixed with an underscore (_). 
This is because, by default. Turbo C starts all names 
with an underscore. You don't need MASM51 or 
QUIRKS if you want to prefix all PUBLIC and EXTRN 
symbols with an underbar (_) for the C language. 

language also tells Turbo Assembler in what order 
procedure arguments were pushed onto the stack by the 
calling module. If you set language to Pascal, Basic, or 
FORTRAN, Turbo Assembler presumes that the argu- 
ments were pushed from left to right, in the order they 
were encountered in the source statement that called the 
procedure. If you set language to C or Prolog, Turbo 
Assembler prestimes that the arguments were pushed in 
reverse order, from right to left in the source statement. 
With C and Prolog, Turbo Assembler also presumes that 
the calling function will remove any pushed arguments 
from the stack. For other languages. Turbo Assembler 
generates the appropriate form of the RET instruction, 
which removes the arguments from the stack before 
returning to the caller. 

If you don't supply language, .MODEL simply defines 
how the segments will be used with the simplified 
segmentation directives. 

The following tables show the default segment attributes 
for each memory model. 

Table 3.1 : Default Segments and Types for Tiny Memory Model 



Directive 


Name 


Align 


Combine 


Class 


Group 


.CODE 


TEXT 


WORD 


PUBLIC 


'CODE' 


DGROUP 


.FARDATA 


FAR DATA 


PARA 


private 


'FAR DATA' 




.FARDATA? 


FAR BSS 


PARA 


private 
PUBLIC 


'FAR BSS' 




.DATA 


DATA 


WORD 


'DATA' 


DGROUP 


.CONST 


CONST 


WORD 


PUBLIC 


'CONST' 


DGROUP 


.DATA? 


BSS 


WORD 


PUBLIC 


'BSS' 


DGROUP 


.STACK 


STACK 


PARA 


STACK 


'STACK' 


DGROUP 
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Table 3.2: Default Segments and Types for Small Memory Model 



Directive 



Name 



Align 



Combine Class 



Group 



CODE 


TEXT 


WORD 


PUBLIC 


'CODE' 




.FARDATA 


FAR DATA 


PARA 


private 


'FAR DATA' 




.FARDATA? 


FAR BSS 


PARA 


private 
'UBLIC 


'FAR BSS' 




DATA 


DATA 


WORD 


'DATA' 


DGROUP 


CONST 


CONST 


WORD 


PUBLIC 


'CONST' 


DGROUP 


DATA? 


BSS 


WORD 


PUBLIC 


'BSS' 


DGROUP 


STACK 


STACK 


PARA 


STACK 


'STACK' 


DGROUP 



Table 3.3: Default Segments and Types for Medium Memory Model 



Directive 



Name 



Align 



Combine Class 



Group 



CODE 


name TEXT 


WORD 


FARDATA 


FAR DATA 


PARA 


FARDATA? 


FAR BSS 


PARA 


DATA 


DATA 


WORD 


CONST 


CONST 


WORD 


DATA? 


BSS 


WORD 


STACK 


STACK 


PARA 



PUBLIC 
private 

Private 
UBLIC 
PUBLIC 
PUBLIC 
STACK 



'CODE' 




'FAR DATA' 




'FAR BSS' 




'DATA' 


DGROUP 


'CONST' 


DGROUP 


'BSS' 


DGROUP 


'STACK' 


DGROUP 



Table 3.4: Default Segments and Types for Compact Memory Model 



Directive 



Name 



Align 



Combine Class 



Croup 



CODE 


TEXT 


WORD 


PUBLIC 


'CODE' 




FARDATA 


FAR DATA 


PARA 


private 


TAR DATA' 




FARDATA? 


FAR BSS 


PARA 


private 
'UBLIC 


'FAR BSS' 




DATA 


DATA 


WORD 


'DATA' 


DGROUP 


CONST 


CONST 


WORD 


PUBLIC 


'CONST' 


DGROUP 


DATA? 


BSS 


WORD 


PUBLIC 


'BSS' 


DGROUP 


STACK 


STACK 


PARA 


STACK 


'STACK' 


DGROUP 



Table 3.5: Default Segments and Types for Large or Huge Memory Model 



Directive 



Name 



Align 



Combine Class 



Group 



.CODE 


name TEXT 


WORD 


PUBLIC 


'CODE' 




.FARDATA 


FAR DATA 


PARA 


private 


'FAR DATA' 




.FARDATA? 


FAR BSS 


PARA 


private 
?UBLIC 


'FAR BSS' 




.DATA 


DATA 


WORD 


'DATA' 


DGROUP 


.CONST 


CONST 


WORD 


PUBLIC 


'CONST' 


DGROUP 


.DATA? 


BSS 


WORD 


PUBLIC 


'BSS' 


DGROUP 


.STACK 


STACK 


PARA 


STACK 


'STACK' 


DGROUP 
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Table 3.6: Default Segments and Types for Turbo Pascal (TPASCAL) Memory Model 



Directive Name Align Combine 


.CODE CODE BYTE PUBLIC 
.DATA DATA WORD PUBLIC 


See also 


.CODE, .DATA, .FARDATA, .FARDATA?, .STACK 


Example 


.MODEL MEDIUM ;set small data, large code 


MODEL 


Function 


Sets the memory model for simplified segmentation 
directives 


Mode 


MASM, Ideal 


Syntax 


MODEL 


See also 


.MODEL 


MULTERRS 



Function 

Mode 

Syntax 

Remarks 



See also 
Example 



Allows multiple errors to be reported on a single source 
line 

MASM, Ideal 

MULTERRS 

MULTERRS lets more than one error or v^arning 
message appear for each source line. This is sometimes 
helpful in locating the cause of a subtle error or when 
the source line contains more than one error. 

Note that sometimes additional error messages can be a 
"chain reaction" caused by the first error condition; 
these "chain" error messages may desist once you 
correct the first error. 

NOMULTERRS 



MULTERRS 

mov ax, [bp+abc 



/produces two errors: 
;1) Undefined symbol: abc 
;2) Need right square bracket 
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NAME 



Function 
Mode 
Syntax 
Remarks 



Example 



Sets the object file's module name 
MASM, Ideal 

NAME module name 

This directive has no effect in MASM mode; it only 
works in Ideal mode. 

Turbo Assembler usually uses the source file name with 
any drive, directory, or extension as the module name. 
Use NAME if you wish to change this default name; 
modulename will be the new name of the module. 

NAME loader 



%NEWPAGE 



Function 
Mode 
Syntax 
Remarks 

See also 
Example 



Starts a new page in the listing file 
MASM, Ideal 

%NEWPAGE 

The source lines appearing after %NEWPAGE will 
begin at the start of a new page in the hsting file. (Same 
as PAGE with no arguments.) 

PAGE 

%NEWPAGE 

; Appears on first line of new page 



%NOCONDS 



Function 

Mode 

Syntax 

Remarks 



Disables the placement of statements in false conditional 
blocks in the listing file 

MASM, Ideal 

%NOCONDS 

%NOCONDS overrides the listing control. When this 
control is in effect, the listing won't show statements 
within conditional blocks, even those that evaluate as 
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See also 
Example 



false and don't result in the evaluation of enclosed 
statements. (Same as .SFCOND.) 

%CONDS, .LFCOND, .SFCOND, .TFCOND 



%NOCONDS 
IF 

mov ax, 1 
ENDIF 



;not in listing, since "IF 0" above 



%NOCREF 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Disables cross-reference listing (CREF) 
MASM, Ideal 

%NOCREF [symbol, ... ] 

%NOCREF stops cross-reference information from 
being accumulated for symbols encountered from this 
point forward in the source file. 

If you use %NOCREF alone without specifying any 
symbols, cross-referencing is disabled completely. If you 
supply one or more symbol names, cross-referencing is 
disabled only for those symbols. (Same as .XCREF.) 

%CREF, .CREF, .XCREF, %CREFALL, %CREFREF, 
%CREFUREF 



%XCREF xyz 
WVAL DW 
xyz DB 



;CREF shows WVAL defined here 
/doesn't appear in CREF 



%NOCTLS 



Function 
Mode 
Syntax 
Remarks 



Disables printing of listing controls 
MASM, Ideal 



INOCTLS 



%NOCTLS reverses the effect of a previous %CTLS 
directive, which caused all listing-control directives to 
be placed in the listing file. After issuing %NOCTLS, all 
subsequent listing-control directives will not appear in 
the listing file. 
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See also 
Example 



This is the default listing-control mode that's in effect 
when Turbo Assembler starts assembling a source file. 



%CTLS 

%NOCTLS 
%LIST 



;this will not appear in listing 



NOEMUL 



Function 

Mode 

Syntax 

Remarks 



See also 
Example 



Forces generation of real 80x87 floating-point 
instructions 

MASM, Ideal 

NOEMUL 

NOEMUL sets Turbo Assembler to generate real 
floating-point instructions to be executed by an 80x87 
coprocessor. You can combine this directive with the 
EMUL directive when you wish to generate real 
floating-point instructions in one portion of a file and 
emulated instructions in another portion. 

NOEMUL is the normal floating-point assembly mode 
that's in effect when Turbo Assembler starts to assemble 
affle. 

EMUL 

NOEMUL /assemble real FP instructions 

finit 

EMUL /back to emulation 



%NOINCL 



Function 
Mode 
Syntax 
Remarks 



See also 



Disables listing of include files 
MASM, Ideal 

%NOINCL 

%NOINCL stops an subsequent INCLUDE file source 
lines from appearing in the listing until a %INCL is 
enabled. This is useful if you have a large INCLUDE file 
that contains things such as a lot of EQU definitions that 
never change. 

%INCL 
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Example 



%NOINCL 

INCLUDE DEFS.INC 



/•doesn't appear in listing 



NOJUMPS 



Function 
Mode 
Syntax 
Remarks 



See also 



Disables stretching of conditional jumps 
MASM, Ideal 

NOJUMPS 

If you use NOJUMPS in conjunction with JUMPS, you 
can control where in your source file conditional jumps 
should be expanded to reach their destination addresses. 

This is the default mode Turbo Assembler uses when it 
first starts assembling a file. 

JUMPS 



%NOLIST 



Function 
Mode 
Syntax 
Remarks 

See also 
Example 



Disables output to listing file 
MASM, Ideal 



%NOLIST 



%NOLIST stops all output to the listing file until a sub- 
sequent %LIST turns the listing back on. This directive 
overrides all other listing controls. (Same as .XLIST.) 

%LIST, .UST, .XLIST 



%NOLIST 
add dx,ByteVar 



;not in listing 



NOLOCALS 



Function 
Mode 
Syntax 
Remarks 



Disables local symbols 
MASM, Ideal 



NOLOCALS 



If local symbols are enabled with the LOCALS directive, 
any symbol starting with two at-signs (@@) is con- 
sidered to be a local symbol. If you use symbols in your 
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See also 
Example 



program that start with two at-signs but you don't want 
them to be local symbols, you can use this directive 
where appropriate. 

Local symbols start off disabled in M ASM mode. 

LOCALS, MASM 

NOLOCALS 
abc PROG 
@@$1: 

loop @@$1 
abc ENDP 
xyz PROC 
@@1: /label conflict with @@1 above 

loop @@1 
xyz ENDP 



%NOMACS 



Function 
Mode 
Syntax 
Remarks 



See also 



Lists only macro expansions that generate code 
MASM, Ideal 

%NOMACS 

%NOMACS prevents the listing source lines that gener- 
ate no code from being listed, for example, comments, 
EQU and = definitions, SEGMENT and GROUP 
directives. 

This is the default listing mode for macros that's in effect 
when Turbo Assembler first starts assembling a source 
file. (Same as .XALL.) 

.LALL, %MACS,.SALL 



NOMASM51 



Function 
Mode 
Syntax 
Remarks 



Disables assembly of certain MASM 5.1 enhancements 
MASM, Ideal 

N0MASM51 

Disables the MASM 5.1 features described under the 
MASM51 directive. This is the default mode when 
Turbo Assembler first starts assembling your source file. 
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See also 
Example 



MASM51 

MASM51 

SLEN SIZESTR <ax,bx> 

N0MASM51 

CATSTR PROC NEAR 



;SLEN = 5 

; CATSTR OK user symbol in 
; non-MASM 5.1 mode 



CATSTR ENDP 



NOMULTERRS 



Function 

Mode 

Syntax 

Remarks 



See also 
Example 



Allows only a single error to be reported on a source 
line. 

MASM, Ideal 

NOMULTERRS 

NOMULTERRS only lets one error or warning message 
appear for each source line. If a source line contains 
multiple errors. Turbo Assembler reports the most- 
significant error first. When you correct this error, in 
many cases the other error messages disappear as well. 
If you prefer to decide for yourself which are the most 
important messages, you can use the MULTERRS 
directive to see aU the messages for each source line. 

By default. Turbo Assembler uses this error-reporting 
mode when first assembling a source file. 

MULTERRS 



NOMULTERRS 
mov ax, [bp+abc 



;one error: 

;1) Undefined symbol: abc 



Will produce the single error message: 

**Error** MULTERRS. ASM (6) Undefined symbol: ABC 
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%NOSYMS 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Disables symbol table in listing file 
MASM, Ideal 



%NOSYMS 



%NOSYMS prevents the symbol table from appearing 
in your file. The symbol table, which shows all the sym- 
bols you defined in your source file, usually appears at 
the end of the listing file. 



%SYMS 



%NOSYMS 



;now we won't get a symbol table 



%NOTRUNC 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Wordwraps too-long fields in listing fQe 
MASM, Ideal 

%NOTRUNC 

The object code field of the listing file has enough room 
to show the code emitted for most instructions and data 
allocations. You can adjust the width of this field with 
the %BIN directive. If a single source line emits more 
code than can be displayed on a single line, the rest is 
normally truncated and therefore not visible. Use the 
%NOTRUNC directive when you wish to see all the 
code that was generated. 

%NOTRUNC also controls whether the source lines in 
the listing file are truncated or will wrap to the next line. 
Use the %TEXT directive to set the width of the source 
field. 

%BIN, %TEXT, %TRUNC 



%NOTRUNC 
DQ 4 DUP (1.2,3.4) 



; wraps to multiple lines 
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NOWARN 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Disables a warning message 
MASM, Ideal 

NOWARN [warnclass] 

If you specify NOWARN without warndass, all warnings 
are disabled. If you follow NOWARN with a warning 
identifier, only that warning is disabled. Each warning 
message has a three-letter identifier that's described 
under the WARN directive. These are the same identi- 
fiers used by the AV command-line option. 



WARN 

NOWARN OVF 

DW lOOOh * 1234h 



/disable arithmetic overflow warnings 
/doesn't warn now 



ORG 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Sets the location counter in the current segment 
MASM, Ideal 

ORG expression 

expression must not contain any forward-referenced 
symbol names. It can either be a constant or an offset 
from a symbol in the current segment or from $, the 
current location counter. 

You can back up the location coimter before data or code 
that has already been admitted into a segment. You can 
use this to go back and fill in table entries whose values 
weren't known at the time the table was defined. Be 
careful when using this technique — you may acci- 
dentally overwrite something you didn't intend to. 

The ORG directive can be used to connect a label with a 
specific absolute address. The ORG directive can also 
set the starting location for .COM fUes (ORG lOOh). 

SEGMENT 



PROG SEGMENT 
ORG lOOh 



/starting offset for .COM file 



132 



Turbo Assembler Reference Guide 



%OUT 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Displays message to screen 
MASM 

%OUT text 

text is any message you want to display. The message is 
written to the standard output device, which is usually 
the screen. If you wish, you can use the DOS redirection 
facility to send screen output to a file. 

Among other things, you can use %OUT so you'll know 
that sections of conditional assembly are being gener- 
ated. (Same as DISPLAY.) 

You can use the substitute operator inside a string 
passed to the %OUT directive; for example, 

MAKE_DATA MACRO VALUE 

%OUT initializing a byte to: SVALUES 

DB VALUE 

ENDM 

DISPLAY 

%OUT Assembling graphics driver 



P186 



Function 
Mode 
See also 



Enables assembly of 80186 instructions 

MASM, Ideal 

J86, .8086, .286, .286C, .286P, .386, .386C, .386P, P8086, 
P286, P286P, P386, P386P 



P286 



Function 
Mode 
See also 



Enables assembly of all 80286 instructions 

MASM, Ideal 

.8086, .186, .286, .286C, .286P, .386, .386C, .386P, P8086, 
P286N, P286P, P386, P386N, P386P 



Chapters, Directives 



133 



P286N 



Function 
Mode 
See also 



Enables assembly of non-privileged 80286 instructions 

MASM, Ideal 

.8086, .186, .286C, .286P, .286, .386, .386C, .386P, P8086, 
P286, P286P, P386, P386N, P386P 



P286P 



Function 
Mode 
See also 



Enables assembly of privileged 80286 instructions 

MASM, Ideal 

.8086, .186, .286C, .286P, .286, .386, .386C, .386P, P8086, 
P286, P286N, P386, P386N, P386P 



P287 



Function 
Mode 
See also 



Enables assembly of 80287 coprocessor instructions 

MASM, Ideal 

.8087, .287, .387, P8087, PN087, P387 



P386 



Function 
Mode 
See also 



Enables assembly of all 80386 instructions 

MASM, Ideal 

.8086, .186, .286C, .286, .286P, .386C, .386P, .386, P8086, 
P286, P286N, P286P, P386N, P386P 



P386N 



Function 
Mode 
See also 



Enables assembly of non-privileged 80386 instructions 

MASM, Ideal 

.8086, .186, .286C, .286, .286P, .386C, .386P, .386, P8086, 
P286, P286N, P286P, P386, P386P 
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P386P 



Function 
Mode 
See also 



Enables assembly of privileged 80386 instructions 

MASM, Ideal 

.8086, .186, .286C, .286, .286P, .386C, .386P, .386, P8086, 
P286, P286N, P286P, P386, P386N 



P387 



Function 
Mode 
See also 



Enables assembly of 80387 coprocessor instructions 

MASM, Ideal 

.8087, .287, .387, 8087, PN087, P287 



P8086 



Function 
Mode 
See also 



Enables assembly of 8086 instructions only 

MASM, Ideal 

186, .286C, .286, .286P, .386C, .386, .386P, .8086, P286, 
P286N, P286P, P386, P386N, P386P 



P8087 



Function 
Mode 
See also 



Enables assembly of 8087 coprocessor instructions 

MASM, Ideal 

.287, .387, .8087, 8087, PN087, P287, P387 



PAGE 



Function 

Mode 

Syntax 

Remarks 



Sets the listing page height and width, starts new pages 

MASM 

PAGE [rows] [,cols] 
PAGE + 

rows specifies the number of lines that will appear on 
each listing page. The minimum is 10 and the maximum 
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See also 
Example 



is 255. cols specifies the number of columns wide the 
page will be. The minimum width is 59; the maximum is 
255. If you omit either rows or cols, the current setting for 
that parameter will remain unchanged. To change only 
the number of columns, precede the column width with 
a comma; otherwise, you'll end up changing the number 
of rows instead. 

If you follow the PAGE directive with a plus sign (+), a 
new page starts, the section number is incremented, and 
the page number restarts at 1. 

If you use the PAGE directive with no arguments, the 
listing resrrrnes on a new page, with no change in section 
number. 

%NEWPAGE, %PAGESIZE 

PAGE ; start a new page 

PAGE ,80 ;set width to 80, don't change height 



%PAGESIZE 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Sets the listing page height and width 
MASM, Ideal 

%PAGESIZE [rows] [,cols] 

rows specifies the number of lines that will appear on 
each listing page. The minimum is 10 and the maximum 
is 255. cols specifies the number of columns wide the 
page will be. The minimum width is 59; the maximum is 
255. 

If you omit either rows or cols, the current setting for that 
parameter will remain unchanged. If you only want to 
change the number of columns, make sure you precede 
the column width with a comma; otherwise, you will 
end up changing the number of rows instead. 



PAGE 

%PAGESIZE 66,132 
%PAGESIZE ,80 



;wide listing, normal height 
;don't change rows, cols = 8C 
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%PCNT 

Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Sets segmentroffset field width in listing file 
MASM, Ideal 

%PCNT width 

width is the number of columns you wish to reserve for 
the offset within the current segment being assembled. 
Turbo Assembler sets the width to 4 for ordinary 16-bit 
segments and sets it to 8 for 32-bit segments used by the 
386 processor. %PCNT overrides these default widths. 

%BIN, %DEPTH, %LINUM, 



%PCNT 3 
ORG 1234h 



;only 234 displayed 



PN087 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Prevents the assembling of coprocessor instructions 
MASM, Ideal 

PN087 

Normally, Borland's Turbo Assembler allows you to 
assemble instructions for the 80x87 coprocessor family. 
Use PN087 if you want to make sure you don't acci- 
dentally use any coprocessor instructions. Also, use 
PN087 if your software doesn't have a floating-point 
emulation package, and you know your program may 
be run on systems without a numeric coprocessor. 

.8087, .287, .387, P8087, P287, P387 



PN087 
fadd 



;this generates an error 
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%POPLCTL 



Function 
Mode 
Syntax 
Remarks 



Recalls listing controls from stack 
MASM, Ideal 

%POPLCTL 

%POPLCTL resets the listing controls to the way they 
were when the last %PUSHLCTL directive was issued. 
All the listing controls that you can enable or disable 
(such as %MACS, %LIST, %INCL, and so on) are 
restored. None of the hsting controls that set field width 
are restored (such as %DEPTH, %PCNT). The listing 
controls are saved on a 16-level stack. This directive is 
particularly useful in macros and include files, where 
you can invoke special listing modes that disappear 
once the macro expansion terminates. 



See also 


%PUSHLCTL 


Example 


%PUSHLCTL 




%NOLIST 




%NOMCS 




%POPLCTL /restore listings 



PROC 



Function 

Mode 

Syntax 



Remarks 



Defines the start of a procedure 
MASM, Ideal 
MASM mode: 

name PROC [distance] [USES registers,] 

[argument [, argument]...] [RETURNS argument [, argument]...] 

Ideal mode: 

PROC name [distance] [USES registers,] 

[argument [, argument ] ...] [RETURNS argument [, argument]...] 

name is the name of a procedure. The optional distance 
can be NEAR or FAR; it defaults to the size of the 
default code memory model. If you are not using the 
simplified segmentation directives (.MODEL, and so 
on), the default size is NEAR. With the tiny, small, and 
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compact models, the default size is also NEAR; all other 
models are FAR. distance determines whether any RET 
instructions encountered within the procedure generate 
near or far return instructions. A FAR procedure is 
expected to be called with a FAR (segment and offset) 
CALL instruction, and a NEAR procedure is expected to 
be called with a NEAR (offset only) CALL. 

registers is a list of registers that the procedxire will use. 
registers must be pushed on entry and popped on exit 
from the procedure. You can supply more than one 
register name by separating the names with spaces. 

argument describes an argument the procedure is called 
with. The language specified with the .MODEL directive 
determines whether the arguments are in reverse order 
on the stack. You must always Ust the arguments in the 
same order they appear in the high-level language func- 
tion that calls the procedure. Turbo Assembler reads 
them in reverse order if necessary. Each argument has the 
following syntax: 

argname[[countl]] [zdistance] PTR] type] [:count2] 

argname is the name you'll use to refer to this argument 
throughout the procedure, distance is optional and can 
be either NEAR or FAR to indicate that the argument is 
a pointer of the indicated size, type is the data type of the 
argument and can be BYTE, WORD, DWORD, 
FWORD, PWORD, QWORD, TBYTE, or a structure 
name, countl and count! are the number of elements of 
the specified type. The total count is calculated as countl 
* countl. 

If you don't specify type, WORD is assumed. 

If you add PTR to indicate that the argument is in fact a 
pointer to a data item. Turbo Assembler emits this 
debug information for Turbo Debugger. Using PTR only 
affects the generation of additional debug information, 
not the code Turbo Assembler generates. You must still 
write the code to access the actual data using the pointer 
argument. 

If you use PTR alone, without specifying NEAR or FAR 
before it. Turbo Assembler sets the pointer size based on 
the current memory model and, for the 386 processor, 
the current segment address size (16 or 32 bit). The size 
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is set to WORD in the tiny, small, and medium memory 
models, and to DWORD for all other memory models 
using 16-bit segments. If you're using the 386 and are in 
a 32-bit segment, the size is set to DWORD for tiny, 
small, and medium models, and to FWORD for 
compact, large, and huge models. 

The optional RETURNS keyword introduces one or 
more arguments that won't be popped from the stack 
when the procedure returns to its caller. Normally, if 
you specify the language as PASCAL or TPASCAL 
when using the .MODEL directive, all arguments are 
popped when the procedure returns. If you place 
arguments after the RETURNS keyword, they will be 
left on the stack for the caller to make use of, and then 
pop. In particular, you must define a Pascal string return 
value by placing it after the RETURNS keyword. 

Use the ENDP directive to end a procedure definition. 
You must explicitly specify a RET instruction before the 
ENDP if you want the procedure to return to its caller. 

Within PROC/ENDP blocks you may use local symbols 
whose names are not known outside the procedure. 
Local symbols start with double at-signs 



You can nest PROC/ENDP directives if you want; if you 
do, the local symbols nest also. 

Argument names that begin with the local symbol prefix 
when local symbols are enabled are limited in scope to 
the current procedure. 

See also ARC, ENDP, LOCAL, LOCALS, USES 

Example ReadLine PROC NEAR 

;body of procedure 
ReadLine ENDP 

call ReadLine 
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PUBLIC 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Declares symbols to be accessible from other modules 
MASM, Ideal 

PUBLIC symbol [, symbol]... 

symbol is published in the object file so that it can be 
accessed by other modules. If you do not make a symbol 
public, it can only be accessed from the current source 
file. 

You can declare the following types of symbols to be 
public: 

■ data variable names 

■ program labels 

■ numeric constants defined with EQU 

COMM, EXTRN, GLOBAL 

PUBLIC XYPROC /make procedure public 
XYPROC PROC NEAR 



PURGE 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Removes a macro definition 
MASM, Ideal 

PURGE ynacrona/ne [,macroname] .. . 

PURGE deletes the macro definition specified by the 
macroname argument. You can delete multiple macro 
definitions by supplying all their names, separated by 
commas. 

You may need to use PURGE to restore the original 
meaning of an instruction or directive whose behavior 
you changed by defining a macro with the same name. 

MACRO 



PURGE add 
add ax, 4 



; behaves as normal ADD now 
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%PUSHLCTL 



Function 
Mode 
Syntax 
Remarks 



See also 


%POPLCTL 


Example 


%PUSHLCTL 




%NOINCL 




%MACS 




%POPLCTL 



Saves listing controls on stack 
MASM, Ideal 

%PUSHLCTL 

%PUSHLCTL saves the current listing controls on a 
16-level stack. Only the listing controls that can be 
enabled or disabled (%INCL, %NOINCL, and so on) are 
saved. The listing field widths are not saved. This 
directive is particularly useful in macros, where you can 
invoke special listing modes that disappear once the 
macro expansion terminates. 



;save listing controls 



;back the way things were 



QUIRKS 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Enables acceptance of MASM bugs 
MASM, Ideal 

QUIRKS 

QUIRKS allows you to assemble a source file that 
makes use of one of the true MASM bugs. You should 
try to stay away from using this directive, since it merely 
perpetuates source code constructs that only work by 
chance. Instead, you should really correct the offending 
source code so that it does what you really intended. 

See the section "Turbo Assembler Quirks Mode" (page 
172) in Appendix B for a complete description of this 
mode. 

MASM, IDEAL 



QUIRKS 
BVAL DB 
mov BVAL,es 



/•load register into byte location 
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.RADIX 


Function 


Sets the default radix for integer constants in 




expressions 


Mode 


MASM 


Syntax 


.RADIX expression 


Remarks 


expression must evaluate to either 2, 8, 10, or 16. Con- 
stants in expression are always interpreted as decimal, no 
matter what the current radix is set to. 


Example 


.RADIX 8 ;set to octal 
DB 77 ;63 decimal 


RADIX 


Function 


Sets the default radix for integer constants in 




expressions 


Mode 


MASM, Ideal 


Syntax 


RADIX 


See also 


.RADIX 


RECORD 


Function 


Defines a record that contains bit fields 


Mode 


MASM, Ideal 


Syntax 


MASM mode: 



Remarks 



name RECORD field [, field]... 

Ideal mode: 

RECORD name field [, field]... 

name identifies the record so that you can use this name 
later when allocating memory to contain records with 
this format. Each field describes a group of bits in the 
record and has the following format: 

fieldname :width[=expression] 

fieldname is the name of a field in the record. If you use 
fieldname in an expression, it has the value of the number 
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See also 
Example 



of bits that the field must be shifted to the right in order 
to place the low bit of the field in the lowest bit in the 
byte or word that comprises the record. 

width is a constant between 1 and 16 that specifies the 
number of bits in the field. The total width of all fields in 
the record cannot exceed 32 bits. If the total number of 
bits in all fields is 8 or less, the record will occupy 1 byte; 
if it is between 9 and 16 bits, it will occupy 2 bytes; 
otherwise, it will occupy 4 bytes. 

expression is an optional field that provides a default 
value for the field; it must be preceded with an equal 
sign (=). When name is used to define storage, this 
default value will be placed in the field if none is 
supplied. Any unused bits in the high portion of the 
record will be initialized to 0. 

The first field defined by RECORD goes into the most- 
significant bits of the record with successive fields fiUing 
the lower bits. If the total width of all the fields is not 
exactly 8 or 16 bits, all the fields are shifted to the right 
so that the lowest bit of the last field occupies the lowest 
bit of the byte or word that comprises the record. 

STRUC 

MyRec RECORD val:3=4, M0DE:2, SIZE: 4 



REPT 



Function 

Mode 

Syntax 

Remarks 



See also 



Repeats a block of statements 
MASM, Ideal 

REPT expression 
statements 

ENDM 

expression must evaluate to a constant and cannot con- 
tain any forward-referenced symbol names. 

The statements within the repeat block are assembled as 
many times as specified by expression. 

REPT can be used both inside and outside of macros. 

ENDM, IRP, IRPC 
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Example 



REPT 4 
shl ax,l 

ENDM 



.SALL 


Function 


Suppresses the listing of all statements in macro 
expansions 


Mode 


MASM 


Syntax 


.SALL 


Remarks 


Use .SALL to cut down the size of your listing file when 
you want to see how a macro gets expanded. 


See also 


.LALL, .XALL, %MACS, %NOMACS 


Example 


.SALL 
MyMacro 4 ; invoke macro 
add ax, si ;this line follows MYMACRO in listing 


SEGMENT 



Function 

Mode 

Syntax 



Remarks 



Defines a segment with full attribute control 
MASM, Ideal 

MASM mode: 

name SEGMENT [align] [comhine] [use] ['class'] 

Ideal mode: 

SEGMENT name [align] [combine] [use] ['class'] 

name defines the name of a segment. If you have already 
defined a segment with the same name, this segment is 
treated as a continuation of the previous one. 

You can also use the same segment name in different 
source files. The linker will combine all segments with 
the same name into a single segment in the executable 
program. 

align specifies the type of memory boundary where the 
segment must start. It can be one of the following: 
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BYTE Use the next available byte address 

WORD Use the next word-aligned address 

DWORD Use the next doubleword-aligned address 

PARA Use the next paragraph address (16-byte 
aligned) 

PAGE Use the next page address (256-byte 
aligned) 

PARA is the default alignment type used if you do not 
specify an align type. 

combine specifies how segments from different modules 
but with the same name will be combined at link time. It 
can be one of the following: 

■ AT expression: Locates the segment at the absolute 
paragraph address specified by expression, expression 
must not contain any forward-referenced symbol 
names. The linker does not generate any data or code 
for AT segments. You usually use AT segments to 
allow symbolic access to fixed memory locations, such 
as the display screen or the ROM BIOS data area. 

■ COMMON: Locates this segment and all other seg- 
ments with the same name at the same address. The 
length of the resulting common segment is the length 
of the longest segment. 

■ MEMORY: Concatenates all segments with the same 
name to form a single contiguous segment. This is the 
same as the PUBLIC combine type. 

■ PRIVATE: Does not combine this segment with any 
other segments. 

■ PUBLIC: Concatenates all segments with the same 
name to form a single contiguous segment. The total 
length of the segment is the sum of aU the lengths of 
the segments with the same name. 

■ STACK: Concatenates all segments with the same 
name to form a single contiguous segment. The linker 
initializes the stack segment (SS) register to the 
beginning of this segment. It initializes the stack 
pointer (SP) register to the length of this segment, 
allowing your program to use segments with this 
combine type as a calling stack, without having to 
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explicitly set the SS and SP registers. The total length 
of the segment is the sum of all the lengths of the 
segments with the same name. 

PRIVATE is the default combine type used if you do not 
specify one. 

use specifies the default word size for the segment, and 
can only be used after enabling the 80386 processor with 
the P386 or P386N directive. It can be one of the 
following: 

■ USE16: This is the default segment type when you do 
not specify a use-segment attribute. A USE16 segment 
can contain up to 64K of code and /or data. If you 
reference 32-bit segments, registers, or constants while 
in a USE16 segment, additional instruction bytes will 
be generated to override the default 16-bit size. 

B USE32: A USE32 segment can contain up to 4 Gb 
(gigabytes) of code and/or data. If you reference 16- 
bit segments, registers, or constants while in a USE32 
segment, additional instruction bytes will be 
generated to override the default 32-bit size. 

class controls the ordering of segments at link time. 
Segments with the same class name are loaded into 
memory together, regardless of the order in which they 
appear in the source file. You must always enclose the 
class name in quotes (' or "). 

The ENDS directive closes the segment opened with the 
SEGMENT directive. You can nest segment directives, 
but Turbo Assembler treats them as unnested; it simply 
resumes adding data or code to the original segment 
when an ENDS terminates the nested segment. 

See also GROUP, MODEL, CODESEG, DATASEG 

Example prog segment para public 'code' 



PROG ENDS 
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•SEQ 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Sets sequential segment-ordering 
MASM 

.SEQ 

.SEQ causes the segments to be ordered in the same 
order in which they were encountered in the source file. 
By default. Turbo Assembler uses this segment-ordering 
when it first starts assembling a source file. The DOS- 
SEG directive can also affect the ordering of segments. 

.SEQ does the same thing as the /S command-line 
option. If you used the /A command-line option to force 
alphabetical segment-ordering, .SEQ will override it. 

.ALPHA, DOSSEG 



.SEQ 
xyz SEGMENT 
xyz ENDS 
abc SEGMENT 
abc ENDS 



;this segment will be first 



.SFCOND 



Function 

Mode 
Syntax 
See also 



Prevents statements in false conditional blocks from 
appearing in the listing file 

MASM 

. SECOND 

%CONDS, .LFCOND, %NOCONDS, .TFCOND 



SIZESTR 



Function 
Mode 
Syntax 
Remarks 



Returns the number of characters in a string 

MASM51, Ideal 

name SIZESTR string 

name is assigned a numeric value that is the number of 
characters in a string. A null string <> has a length of 
zero. 
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See also 
Example 



SUBSTR, CATSTR, INSTR 



RegList EQU <si di> 
RegLen SIZESTR RegList 



;RegLen = 5 



.STACK 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Defines the start of the stack segment 
MASM 

.STACK [size] 

size is the number of bytes to reserve for the stack. If you 
do not supply a size, the .STACK directive reserves 1 Kb 
(1024 bytes). 

You usually only need to use .STACK if you are writing 
a standalone assembler program. If you are writing an 
assembler routine that will be called from a high-level 
language, that language will normally have set up any 
stack that is required. 

.CODE, .CONST, .DATA, .DATA?, .FARDATA, 
.FARDATA?, .MODEL, STACK 



.STACK 200h 



/•allocate 512 byte stack 



STACK 



Function 
Mode 
See also 



Defines the start of the stack segment 

MASM, Ideal 

.CODE, .CONST, .DATA, .DATA?, .FARDATA, 
.FARDATA?, .MODEL, .STACK 



STRUC 



Function 


Defines a structure 


Mode 


MASM, Ideal 


Syntax 


MASM mode: 




name STRUC 




fields 




[name] ENDS 
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Ideal mode: 

STRUC name 

fields 
ENDS [name] 

Remarks The difference in how STRUC is handled in Ideal and 

MASM mode is only in the order of the directive and the 
structure name on the first line of the definition, and the 
order of the ENDS directive and the optional structure 
name on the last line of the definition. In Turbo 
Assembler, you can nest the STRUC directive and also 
combine it with the UNION directive. 

name identifies the structure, so you can use this name 
later when allocating memory to contain structures with 
this format. 

fields define the fields that comprise the structure. Each 
field uses the normal data allocation directives (DB, 
DW, and so on) to define its size, fields may be named or 
remain nameless. The field names are like any other 
symbols in your program — they must be unique. In 
Ideal mode, the field names do not have to be unique. 

You can supply a default value for any field by putting 
that value after the data allocation directive, exactly as if 
you were initializing an individual data item. If you do 
not want to supply a default value, use the ? indetermi- 
nate initialization symbol. When you use the structure 
name to actually allocate data storage, any fields 
without a value will be initialized from the default 
values in the structure definition. If you don't supply a 
value, and there is no default value, ? wUl be used. 

Be careful when you supply strings as default values; 
they will be truncated if they are too long to fit in the 
specified field. If you specify a string that is too short for 
the field in MASM mode, it will be padded with spaces 
to fill out the field. When in Ideal mode, the rest of the 
string from the structure definition will be used. This 
lets you control how the string will be padded by 
placing appropriate values in the structure definition. 

At any point while declaring the structure members, you 
may include a nested structure or union definition by 
using the STRUC or UNION directive instead of one of 
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See Also 
Example 



the data allocation directives, or you may use the name 
of a previously defined structure. 

When you nest structures or unions using the STRUC or 
UNION directive, you still access the members as if the 
structure only has one level by using a single period (.) 
structure member operator. When you nest structures by 
using a previously defined structure name, you use 
multiple period operators to step down through the 
structures. 



ENDS, 


UNION 


IDEAL 




.MODEL small 


DATASEG 




STRUC B 




Bl DD 





B2 DB 


7 


ENDS 




STRUC A 




Al DW 


9 


A2 DD 


9 


BINST 


B <> 


STRUC 




D 


DB "XYZ" 


E 


DQ 1.0 


ENDS 




ENDS 




AINST 


A <> 


CINST 


A ? 


DINST 


A 


CODESEG 




raov 


al, [AINST. BINST. B2] 


mov 


al, [AINST. D] 


mov 


ax, [WORD CINST. BINST. Bl] 


END 





; first field 
/second field 



SUBSTR 



Function 

Mode 

Syntax 



Defines a new string as a substring of an existing string 
MASM51, Ideal 

name SUBSTR string, positionl, size] 
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Remarks 



See also 
Example 



name is assigned a value consisting of characters from 
string starting at position, and with a length of size. The 
first character in the string is position 1. If you do not 
supply a size, all the remaining characters in string are 
returned, starting from position. 

string may be one of the following: 

■ a string argument enclosed in angle brackets, like 
<abc> 

■ a previously defined text macro 

■ a numeric string substitution starting with percent (%) 

CATSTR, INSTR, SIZESTR 



N = OAh 

HEXC SUBSTR <0123456789ABCDEF>,N +1,1 



;HEXC = "A" 



SUBTTL 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Sets subtitle in listing file 
MASM 

SUBTTL text 

The subtitle appears at the top of each page, after the 
name of the source file, and after any title set with the 
TITLE directive. 

You may place as many SUBTTL directives in your 
program as you wish. Each directive changes the sub- 
title that will be placed at the top of the next listing page. 

% SUBTTL 

SUBTTL Video driver 



% SUBTTL 



Function 
Mode 
Syntax 
Remarks 



Sets subtitle in listing file 
MASM, Ideal 

%SUBTTL "text" 

The subtitle text appears at the top of each page, after the 
name of the source file, and after any title set with the 
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See also 
Example 



% TITLE directive. Make sure that you place the subtitle 
text between quotes (""). 

You may place as many %SUBTTL directives in your 
program as you wish. Each directive changes the 
subtitle that will be placed at the top of the next listing 
page. 

SUBTTL 

%SUBTTL "Output routines" 



%SYMS 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Enables symbol table in listing file 
MASM, Ideal 

%SYMS 

Placing %SYMS anywhere in your source file causes the 
symbol table to appear at the end of the listing file. (The 
symbol table shows all the symbols you defined in your 
source file.) 

This is the default symbol listing mode used by Turbo 
Assembler when it starts assembling a source file. 

%NOSYMS 



%SYMS 



/symbols now appear in listing file 



% TAB SIZE 



Function 
Mode 
Syntax 
Remarks 

See also 
Example 



Sets tab colimnn width in the listing file 
MASM, Ideal 

%TABSIZE width 

width is the number of columns between tabs in the 
listing file. The default tab column width is 8 columns. 

%PAGE, %PCNT, %BIN, %TEXT 

%TABSIZE 4 /small tab columns 
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%TEXT 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Sets width of soiirce field in listing file 
MASM, Ideal 

%TEXT width 

width is the number of columns to use for source lines in 
the listing file. If the source line is longer than this field, 
it will either be truncated or wrapped to the following 
line, depending on whether you've used %TRUNC or 
%NOTRUNC. 

%BIN, %DEPTH, %NOTRUNC, %PCNT, %TRUNC 

%TEXT 80 ;show 80 columns from source file 



.TFCOND 



Function 
Mode 
Syntax 
Remarks 



See also 



Toggles conditional block-listing mode 
MASM 

.TFCOND 

Normally, conditional blocks are not listed by Turbo 
Assembler, and the first .TFCOND encountered enables 
a listing of conditional blocks. If you use the /X 
command-line option, conditional blocks start off being 
listed, and the first .TFCOND encountered disables 
Usting them. Each time .TFCOND appears in the source 
file, the state of false conditional listing is reversed. 

%CONDS, .LFCOND, %NOCONDS, .SECOND 



TITLE 



Function 
Mode 
Syntax 
Remarks 



Sets title in listing file 
MASM 



TITLE text 



The title text appears at the top of each page, after the 
name of the source file and before any subtitle set with 
the SUBTTL directive. 
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See also 
Example 



You may only use the TITLE directive once in your 
program. 

SUBTTL, %SUBTTL, %TITLE 

TITLE Sort Utility 



% TITLE 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Sets title in listing file 
MASM, Ideal 

%TITLE "text" 

The title text appears at the top of each page, after the 
name of the source file and before any subtitle set with 
the %SUBTTL directive. Make sure that you place the 
title text between quotes (""). 

You may only use the % TITLE directive once in your 
program. 

SUBTTL, %SUBTTL, TITLE 

%TITLE "I/O Library" 



%TRUNC 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Truncates listing fields that are too long 
MASM, Ideal 

%TRUNC 

%TRUNC reverses the effect of a previous %NO- 
TRUNC directive. This directive changes the object-code 
field and the source-line field so that too-wide fields are 
truncated and excess information is lost. 

%NOTRUNC 



%TRUNC 
DD 1,2,3,4,5 



/don't see all fields 
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UDATASEG 



Function 
Mode 
See also 



Defines the start of an uninitialized data segment 

MASM, Ideal 

.CODE, .CONST, .DATA, DATA?, .FARDATA, 
.FARDATA?, .MODEL, .STACK 



UFARDATA 



Function 
Mode 
See also 



Defines the start of an uninitialized far data segment 

MASM, Ideal 

.CODE , .DATA, .FARDATA, .FARDATA?, .MODEL, 
.STACK 



UNION 



Function 

Mode 

Syntax 



Remarks 



Defines a union 

MASM, Ideal (disabled by QUIRKS) 

MASM mode: 

NAME UNION 

fields 
[name] ENDS 

Ideal mode: 

UNION NAME 

fields 
ENDS [name] 

The only difference in how UNION behaves in Ideal 
and MASM mode is in the order of the directive and the 
union name on the first line of the definition, and the 
order of the ENDS directive and the optional union 
name on the last line of the definition. Turbo Assembler 
allows you to nest UNION and to combine it with 
STRUC. 

A UNION is just like a STRUC except that all its 
members have an offset of zero (0) from the start of the 
union. This results in a set of fields that are overlayed, 
allowing you to refer to the memory area defined by the 
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union with different names and different data sizes. The 
length of a union is the length of its largest member, not 
the sum of the lengths of its members as in a structure. 

name identifies the imion, so you can use this name later 
when allocating memory to contain unions with this 
format. 

fields define the fields that comprise the union. Each field 
uses the normal data allocation directives (DB, DW, etc.) 
to define its size. The field names are like any other 
symbols in your program — they must be unique. 

You can supply a default value for any field by putting 
that value after the data allocation directive, exactly as if 
you were initializing an individual data item. If you 
don't want to supply a default value, use the ? indeter- 
minate initialization symbol. When you use the union 
name to actually allocate data storage, any fields that 
you don't supply a value for will be initialized from the 
default values in the structure definition. If you don't 
supply a value and there is no default value, ? will be 
used. 

Be careful when you supply strings as default values; 
they will be truncated if they are too long to fit in the 
specified field. If you specify a string that is too short for 
the field, it will be padded with spaces to fill out the 
field. 

At any point while declaring the union members, you 
may include a nested structure or union definition by 
using the STRUC or UNION directive instead of one of 
the data-aUocation directives. When you nest structures 
and unions using the STRUC or UNION directive, you 
still access the members as if the structure only has one 
level by using a single period (.) structure member 
operator. When you nest unions by using a previously 
defined union name, you use multiple period operators 
to step down through the structures and unions. 



See also ENDS, UNION 

Example union b 

BMEMl DW ? 

BMEM2 DB ? 
ENDS 
UNION A 
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B DW ? 


; first field— offset 


C DD ? 


; second field — offset 


BUNION B <> 


; starts at 


STRUC 




D DB "XYZ" 


;at offset 


E DQ 1.0 


;at offset 1 


ENDS 




ENDS 




AINST A <> 


/allocate a union of type A 


mov al, [AINST. BUNION. BMEMl] 


/multiple levels 


mov al, [AINST. D] 


/single level 



USES 



Function 
Mode 
Syntax 
Remarks 



See also 
Example 



Indicates register usage for procedures 
MASM, Ideal 

USES register [, register] ... 

USES appears within a PROC/ENDP pair and indicates 
which registers you want to have pushed at the begin- 
ning of the procedure and which ones you want popped 
just before the procedure returns. 

register can be any register that can be legally PUSHed 
or POPped. There is a limit of 8 registers per procedure. 

Notice that you separate register names with commas, 
not with spaces like you do when specifying the 
registers as part of the PROC directive. You can also 
specify these registers on the same line as the PROC 
directive, but this directive makes your procedure 
declaration easier to read and also allows you to put the 
USES directive inside a macro that you can define to set 
up your procedure entry and exit. 

You must use this directive before the first instruction 
that actually generates code in your procedure. 

Note: USES is only available when used with language 
extensions to a .MODEL statement. 

ARG, LOCALS, PROC 

MyProc PROC 
USES cx,si,di 

mov ex, 10 
rep movsb 



158 



Turbo Assembler Reference Guide 



ret 

MyProc ENDP 



;this will pop CX, SI, & DI registers 



WARN 



Function 
Mode 
Syntax 
Remarks 



Enables a warning message 
MASM, Ideal 

WARN [warnclass] 

If you specify WARN without warnclass, all warnings are 
enabled. If you follow WARN with a warning identifier, 
only that warning is enabled. Each warning message has 
a three-letter identifier: 



ALN 

ASS 

BRK 


Segment alignment 
Assumes segment is 16-bit 
Brackets needed 


ICG 
LCO 


Inefficient code generation 
Location counter overflow 


OPI 


Open IF conditional 


OPP 
OPS 
OVF 


Open procedure 
Open segment 
Arithmetic overflow 


PDC 
PRO 


Pass-dependent construction 
Write-to-memory in protected mode needs 
CS override 


PQK 

RES 

TPI 


Assuming constant for [const] warning 
Reserved word warning 
Turbo Pascal illegal warning 



These are the same identifiers used by the /W 
command-hne option. 



See also 


WARN 




Example 


NOWARN OVF 


/disable arithmetic overflow warnings 




DW lOOOh * 1234h 


; doesn't warn now 
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.XALL 

Function 
Mode 
See also 



Lists only macro expansions that generate code or data 

MASM 

XALL, %MACS, %NOMACS, .SALL 



.XCREF 



Function 
Mode 
See also 



Disables cross-reference listing (CREF) 

MASM 

%CREF, .CREF, %NOCREF 



.XLIST 



Function 
Mode 
See also 



Disables output to listing file 

MASM 

%LIST, .LIST, %NOLIST 
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Turbo Assembler Syntax Summary 



This appendix uses a inodified Backus-Naur form (BNF) to summarize the 
syntax for Turbo Assembler expressions, both in MASM mode and in Ideal 
mode. 

Note: In the following sections, the ellipses (...) mean the same element is 
repeated as many times as it is found. 



Lexical Grammar 



valid_line 

D white_space valid Jine 

■ punctuation validjine 

H number_string validjine 
m id_string validjine 
Bnull 

whitejspace 

■ space_char whitejspace 
m spacejchar 
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space_char 

u All control characters, characters > 128, ' ' 

idjstring 

■ idjchar id_strng2 

idjstmgl 

■ id_chr2 id_strng2 
mnull 

idjchar 

■ $,%,_, ?, alphabetic characters 

idjchrl 

■ id_chars plus numerics 

numherjstring 

■ num_string 
u str_string 

numjstring 

u digits alphanums 
m digits '.' digits exp 

■ digits exp ; Only ifMASM mode in a DD, DQ, or DT 

digits 

■ digit digits 
B digit 

digit 

u through 9 
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alphanums 

u digit alphanum 
u alpha alphanum 
unull 

alpha 

■ alphabetic characters 

exp 

■ E + digits 

■ E - digits 
m E digits 
mnull 

strjstring 

Q Quoted string, quote enterable by two quotes in a row 

punctuation 

D Everything that is not a space_char, id_char, "", '"", or digits 

The period (.) character is handled differently in MASM mode and Ideal 
mode. This character is not required in floating-point numbers in MASM 
mode and also cannot be part of a symbol name in Ideal mode. In MASM 
mode, it is sometimes the start of a symbol name and sometimes a punc- 
tuation character used as the structure member selector. 

Here are the rules for the period (.) character: 

1. In Ideal mode, it is always treated as punctuation. 

2. In MASM mode, it is treated as the first character of an ID in the 
following cases: 

a. When it is the first character on the line, or in other special cases like 
EXTRN and PUBLIC symbols, it gets attached to the following 
symbol if the character that follows it is an id_chr2, as defined in the 
previous rules. 
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b. If it appears other than as the first character on the line, or if the 
resulting symbol would make a defined symbol, the period gets 
appended to the start of the symbol following it. 



MASM Mode Expression Grammar 

tnexprl 

■ 'SHORT mexprl 
u '.TYPE' mexprl 

u 'SMALL' mexprl (16-hit offset cast [386 only]) 
m 'LARGE' mexprl (32-bit offset cast [386 only]) 
m mexprl 

mexprl 

u mexpr3 'OR' mexpr3 ... 
m mexpr3 'XOR' mexpr3 ... 
u mexpr3 

mexprS 

■ mexpr4 'AND' mexpr4 . . . 

■ mexpr4 

mexpr4 

■ 'NOT mexpr4 
u mexprS 

mexprS 

m mexpr6 'EQ' mexpr6 . . . 
u mexpr6 'NE' mexpr6 . . . 
m mexpr6 'LT mexpr6 . . . 

■ mexpr6 'LE' mexpr6 . . . 

■ mexpr6 'GT mexpr6 ... 
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■ mexprS 'GE' mexpr6 . . . 

■ mexprS 

mexprG 

■ mexprJ '+' mexprJ . . . 
B mexprV '-' mexpr? . . . 

■ mexpr? 

mexprJ 

m mexprS '*' mexprS . . . 
m mexprS '/' mexprS . . . 
u mexprS 'MOD' mexprS 
m mexprS 'SHR' mexprS . . 
B mexprS 'SHU mexprS . . 
H mexprS 

mexprS 

B mexpr9 'PTR' mexprS 

fl mexprd 

B 'OFFSET mexprS 

u 'SEC mexprS 

u 'TYPE' mexprS 

B 'THIS' mexprS 

mexprd 

B mexprlO ':' mexprlO . . . 
B mexprlO 

mexprlO 

B '+' mexprlO 
B '-' mexprlO 
umexprll 
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mexprll 

■ 'HIGH' mexprll 

■ 'LOW mexprll 

■ mexprll 

mexprll 

u mexprlS mexprl3 . . . (Implied addition only if '[' or '(' present) 

■ mexprll mexprlS '.' mexprS 

tnexprlS 

■ 'LENGTH' id 

■ 'SIZE' id 

■ 'WIDTH' id 
n 'MASK' id 

■ '(' mexprl ')' 
u '[' mexprl 'Y 
mid 

■ const 

Ideal Mode Expression Grammar 

pointer 

■ 'SMALL' pointer (16-bit offset cast [386 onlyl) 
u 'LARGE' pointer (32-bit offset cast [386 only]) 
u type 'PTR' pointer 

■ type 'LOW pointer (Low caste operation) 
u type 'HIGH' pointer (High caste operation) 
m type pointer 

m pointer! 

type 

■ 'UNKNOWN' 

■ 'BYTE' 
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■ 'WORD' 

n 'DWORD' 

■ 'QWORD' 
m 'PWORD' 
u 'TBYTE' 

u 'SHORT 

■ 'NEAR' 
u 'FAR' 

■ structjd 

■ 'TYPE' pointer 

pointer! 

B -pointer^ '.' id (Structure item operation) 

■ pointer^ 

pointers 

B expr ':' pointer^ 
uexpr 

expr 

B 'SYMTYPE' expr (Symbol type operation) 
mexprl 

exprl 

B exprdt 'OR' expr3 . . . 
B expr3 'XOR' exprS . . . 
uexpr3 

exprS 

B expr4 'AND' expr4 . . . 
uexpr4 
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expr4 

B 'NOT expr4 
mexprS 

exprS 

■ expr6 'EQ' exprS ... 

■ exprS 'NE' exprS . . . 

■ expr6 'LT exprS . . . 

■ expr6 'LE' exprS . . . 

■ expr6 'GT exprS . . . 
m exprB 'GE' exprS ... 
mexprS 

expr6 

m expr? '+' expr? . . . 
m expr? '-' expr? . . . 
uexpr? 

expr? 

■ exprS '*' exprS . . . 
m exprS 7' exprS . . . 

■ exprS 'MOD' exprS 
m exprS 'SHR' exprS . . 
B exprS 'SHU expr 8 . . 
KexprS 

exprS 

m '+' exprS 
u '-' exprS 
mexprd 

expr9 

u 'HIGH' expr9 
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m'L0Wexpr9 
u exprlO 

exprlO 

■ 'OFFSET pointer 

■ 'SEC pointer 
u 'SIZE' id 

■ 'LENGTH' id 

■ 'WIDTH' id 
u 'MASK' id 
uid 

m const 

B '(' pointer ')' 

u 'I' pointer 'I (Always means 'contents-of ') 
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Compatibility Issues 



Turbo Assembler in MASM mode is very compatible with MASM version 
4.0, and additionally supports all the extensions provided by MASM 
versions 5.0 and 5.1. However, 100% compatibility is an ideal that can only 
be approached, since there is no formal specification for the language and 
different versions of MASM are not even compatible with each other. 

For most programs, you will have no problem using Turbo Assembler as a 
direct replacement for MASM version 4.0 or 5.1. Occasionally, Turbo 
Assembler will issue a warning or error message where MASM would not, 
which usually means that MASM has not detected an erroneous statement. 
For example, MASM accepts 

abc EQU (BP+2] 
PUBLIC abc 

and generates a nonsense object file. Turbo Assembler correctly detects this 
and many other questionable constructs. 

If you are having trouble assembling a program with Turbo Assembler, you 
might try using the QUIRKS directive; for example, 

TASM /JQUIRKS MYFILE 

which may make your program assemble properly. If it does, add QUIRKS 
to the top of your source file. Even better, review this appendix and 
determine which statement in your source file needs the QUIRKS directive. 
Then you can rewrite the line(s) of code so that you don't even have to use 
QUIRKS. 

If you're using certain features of MASM version 5.1, you'll need MASM51 
in your source file. These capabilities are discussed later in this appendix. 
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Environment Variables 



In keeping with the approach used by other Borland language products. 
Turbo Assembler does not use environment variables to control default 
options. Instead, you can place default options in a configuration file and 
then set up different configuration files for different projects. See Chapter 3 
in the User's Guide for a discussion of how to do this. 

If you have used the INCLUDE or MASM environment variables to 
configure MASM to behave as you wish, you will have to make a configu- 
ration file for Turbo Assembler. Any options that you have specified using 
the MASM variable can simply be placed in the configuration file. Any 
directories that you have specified using the INCLUDE variable should be 
placed in the configuration file using the /I command-line option. 



Microsoft Binary Floating-Point Format 

Older versions of MASM by default generated floating-point numbers in a 
format incompatible with the IEEE standard floating-point format. MASM 
version 5.1 generates IEEE floating-point data by default and has the 
•MSFLOAT directive to specify that the older format be used. 

Turbo Assembler does not support the old floating-point format, and 
therefore does not let you use .MSFLOAT. 



Turbo Assembler Quirks Mode 

Some MASM features are so problematic in nature that they weren't 
included in Turbo Assembler's MASM mode. However, programmers 
occasionally like to take advantage of some of these "quirky" features. For 
that reason. Turbo Assembler includes Quirks mode, which emulates these 
potentially troublesome features of MASM. 

You can enable Quirks mode either with the QUIRKS keyword in your 
source file or by using the /JQUIRKS command-line option when running 
Turbo Assembler. 

The following constructs will cause Turbo Assembler to generate error 
messages in MASM mode, but will be accepted in Quirks mode. 
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Byte Move to/ from Segment Register 

MASM does not check the operand size when moving segment registers to 
and from memory. For example, the following is perfectly acceptable under 
MASM: 

SEGVAL D... ? 
USEFUL DB ? 

mov SEGVAL, es /overwrites part of "USEFUL"! 

This is clearly a programming error that only works because the corruption 
of USEFUL does not affect the program's behavior. Rather than using 
Quirks mode, redefine SEGVAL to be a DW, as was presumably intended. 



Erroneous Near Jump to Far Label or Procedure 

With MASM, a far jump instruction to a target within the same segment 
generates a near or a short jump whether or not the target is overridden 
with FAR PTR: 

CODE SEGMENT 

jmp abc 

jmp FAR PTR abc /doesn't generate far JMP 
abc LABEL FAR 
CODE ENDS 

Turbo Assembler normally assembles a far JMP instruction when you teU it 
that the destination is a far pointer. If you want it to behave as MASM does 
and always treat it as a short or near jump if the destination is in the same 
segment, you must enable Quirks mode. 



Loss of Type Information with = and EQU Directive 

Examine the following code fragment: 

X DW 

Y = OFFSET X 
mov ax,Y 

MASM will generate the instruction MOV AX,[X] here, where Turbo 
Assembler will correctly generate MOV AX,OFFSET X. This happens 
because MASM doesn't correctly save all the information that describes the 
expression on the right side of the = directive. 

This also happens when using the EQU directive to define symbols for 
numeric expressions. 
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Segment' Alignment Checking 



MASM allows the ALIGN directive to specify an alignment that is more 
stringent than that of the segment in which it is used. For example, 

CODE SEGMENT WORD 

ALIGN 4 /segment is only word aligned 
CODE ENDS 

This is a dangerous thing to do, since the linker may undo the effects of the 
ALIGN directive by combining this portion of segment CODE with other 
segments of the same name in other modules. Even then, you can't be 
guaranteed that the portion of the segment in your module will be aligned 
on anything better than a word botmdary. 

You must enable Quirks mode to accept this basically meaningless 
construct. 



Signed Immediate Arithmetic and Logical 
Instructions 

MASM version 4.0 only sign-extends immediate operands on arithmetic 
instructions. When Turbo Assembler is not in Quirks mode, it does sign- 
extension on immediate operands for logical instructions as well. This 
results in shorter, faster instructions, but changes the size of code segments 
containing these constructs. This may cause problems with self-modifying 
code or any code that knows approximately how long the generated 
instructions are. The following code shows an instruction that both MASM 
and Turbo Assembler generate correctly, and another that Turbo Assembler 
generates correctly and MASM version 4.0 does not: 

add ax,-l ;MASM and Turbo do sign-extend 
xor cx,OFFFFh ;MASM 4 uses word immediate 

Here MASM version 4.0 generates the byte sequence 81 Fl FFFF for the 
XOR instruction, and Turbo Assembler generates the shorter but compa- 
tible 83 Fl FF. 



Masm 5,1 Features 

Some of the new features introduced with MASM version 5.1 are always 
available when using Turbo Assembler. Other features must be enabled 
with the MASM51 directive. Some features of MASM 5.1 and Turbo 
Assembler (implemented more powerfully by Turbo Assembler) are 
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discussed in a previous section, "Turbo Assembler Quirks Mode," on page 
172. 

When Turbo Assembler first starts assembling your source file, it is in 
MASM mode with MASM 5.1 features disabled. This is like starting your 
program with the MASM and NOMASM51 directives. 

Each of the extensions listed here is outlined in more detail Chapter 2, 
"Operators," or Chapter 3, "Directives" in this book. 

The following MASM 5.1 features are always available: 

■ Parameters and local arguments to PROC directive 

■ .TYPE operator extensions 

■ COMM directive extension 

H .CODE sets CS ASSUME to current segment 

■ .MODEL directive high-level language support 

■ List all command-line option (/LA) 

B Additional debug information with DW, DD, and DF directives 

B ELSEIF family of directives 

B @Cpu and ©WordSize directives 

B % expression operator with text macros 

B DW, DD, and DF debug information extensions 

The following features are available when you use MASM51: 

B SUBSTR, CATSTR, SIZESTR, and INSTR directives 
B Line continuation with backslash 

These features are only available when you use both MASM51 and 
QUIRKS: 

B Local labels defined with @@ and referred to with @F and @B 
B Redefinition of variables inside PROCs; :: definitions 
B Extended model PROCs are all PUBLIC 

Masm 51/Qutrks Mode Features 

Since several features of MASM 5.1 adversely affect some of Turbo 
Assembler's features, we've provided an alternative through Turbo 
Assembler that achieves what MASM 5.1 intended. To use these features, 
you must enable Quirks mode with the QUIRKS directive and the MASM 
5.1 features with the MASM51 directive. 
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Here is a short summary of what is covered under the various operating 
modes of TASM: 

QUIRKS 

1. Allows far jumps to be generated as near or short if CS assumes agree. 

2. Allows all instruction sizes to be determined in a binary operation 
solely by a register, if present. 

3. Destroys OFFSET, segment override (and so on) information on = or 
numeric EQU assignments. 

4. Forces EQU assignments to expressions with PTR or : in them to be text. 

5. Disables UNION directive. 

6. Allows GLOBAL directive to be overridden. 

MASM51 

1. Enables Instr, Catstr, Substr, Sizestr, and \ line continuations. 

2. Makes EQU's to keywords TEXT instead of ALIASes. 

3. No longer discards leading whitespace on %textmacro in macro 
arguments. 

MASM51 and QUIRKS 

Everything listed under QUIRKS and MASM51 in this summary, and the 
following: 

1. Enables @@F and @@B local labels. 

2. In extended models, automatically makes PUBLIC procedure names. 

3. Makes near labels in PROCs redefinable in other PROCs. 

4. Enables :: operator to define symbols that can be reached outside of 
current PROC. 
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Turbo Assembler Highlights 



Besides its high compatibility with MASM, Turbo Assembler has a number 
of enhancements that you can use simultaneously with the typical MASM- 
style statements. These enhancements can be used both in Ideal mode and 
in MASM mode. (Chapter 12 in the User's Guide provides you with more 
details about Ideal mode.) 

Here we'll introduce you to each of the enhancements and point you to 
where more-detailed discussions of each topic can be found in the manual. 



Extended Command-Line Syntax 

Turbo Assembler has a greatly improved command-line sjmtax that is a 
superset of the MASM command-line syntax. You can specify multiple files 
to assemble by entering each individually or by using wildcards (* and ?). 
You can also group files so that one set of command-line options applies to 
one set of files, and another set applies to a second set of files. For a 
complete description of Turbo Assembler command-line options, turn to 
Chapter 3 of the User's Guide. 



GLOBAL Directive 

The GLOBAL directive lets you define variables as a cross between an 
EXTRN and a PUBLIC. This means you can put GLOBAL definitions in a 
header file that's included in all source modules and then define the data in 
just one module. This gives you greater flexibility, since you can initialize 



Appendix C. Turbo Assembler Highlights 1 77 



data defined with the GLOBAL directive and you can't with the COMM 
directive. 

The section entitled "The GLOBAL Directive" in Chapter 5 of the User's 
Guide shows you how to use this directive. You can also refer to Chapter 3 
in this book for a complete definition of GLOBAL. 



Local Symbols 

The LOCALS and NOLOCALS directives control whether symbols that 
start with two at-signs (@@) are local to a block of code. 

For more information on local symbols, refer to the section "Local Labels" 
in Chapter 10 of the User's Guide. These two directives are also defined in 
Chapter 3 in this book. 



Conditional Jump Extension 

The JUMPS and NOJUMPS control whether conditional jumps get 
extended into the "opposite sense" condition and a near jump instruction. 
This lets you have a conditional jump with a destination address further 
away than the usual -128 to +127 bytes. 

The section entitled "Automatic Jump Sizing" in Chapter 10 of the User's 
Guide discusses how to use this feature. 



Ideal Mode 

Turbo Assembler's Ideal mode gives you a new and more rational way to 
construct expressions and instruction operands. By learning just a few 
simple rules, you can handle complex instruction operands in a better 
manner. (See Chapter 12 of the User's Guide for an introduction to the 
power of Ideal mode.) 



UNION Directive/STRUC Nesting 

Unions are like structures defined with the STRUC directive except that all 
the members have an offset of zero (0) from the start of the structure, 
effectively "overlaying" all the members. 

In Turbo Assembler, you can nest STRUC and also combine it with 
UNION. The section entitled "The STRUC Directive" in Chapter 10 of the 
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User's Guide shows you how to use this directive; Chapter 3 in this book 
provides a complete definition of both STRUC and UNION. 



EMUL and NOEMUL Directives 

You can control whether floating-point instructions are emulated or are real 
coprocessor instructions with the EMUL and NOEMUL directives. Within 
a single source file, you can switch back and forth as many times as you 
wish between emulated and real floating-point instructions. 



Explicit Segment Overrides 

The Turbo Assembler lets you explicitly force a segment override to be 
generated on an instruction by using one of the SEGCS, SEGDS, SEGES, 
SEGSS, SEGFS, or SEGGS overrides. They function much like the REP 
and LOCK overrides. 

The section entitled "Segment Override Prefixes" in Chapter 10 of the 
User's Guide shows you how to use these overrides. 



Constant Segments 

The Turbo Assembler lets you use a constant value any time that a segment 
value should be supplied. You can also add a constant value to a segment. 
For example, 

jmp FAR PTR OFFFFh:0 ;jump into the ROM BIOS 

LOWDATA SEGMENT AT 

ASSUME DS:LOWDATA+40h ;DS points to BIOS data area 
mov ax,DS:[3FH] ;read word from BIOS data area 

LOWDATA ENDS 

The section entitled 'The SEGMENT Directive" in Chapter 10 of the User's 
Guide explains this in more detail. 



Extended LOOP Instruction in 386 Mode 

When you are writing code for the 80386, Turbo Assembler lets you 
determine explicitly whether the LOOP instruction should use the CX or 
the ECX register as its counter. 

The section entitled "New Versions of LOOP and JCXZ" in Chapter 11 of 
the User's Guide shows you how to use this instruction. 
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Extended Listing Controls 

You have much greater control over the format and the content of the 
listing file with Turbo Assembler. You can control whether INCLUDE files 
are listed, push and pop the listing control state, and control the width of 
all the fields in the listing, including whether they get truncated or wrap to 
the next line. 

Chapter 5 of the User's Guide provides a description of all the options you 
can use. 



Alternate Directives 

The Turbo Assembler provides alternative keywords for a number of 
directives, in particular those that start with a period (.). All alternative 
listing control directives start with a percent sign (%), and all alternative 
processor control directives start with a P. 

Refer to Chapter 3 in this book for a complete list of all the directives that 
Turbo Assembler supports. 



Predefined Variables 

The Turbo Assembler defines a number of variables that have a value you 
can access from your source files. These include ??date, ??time, ??£ilename, 
and ??version, in addition to the predefined variables supported for MASM 
5.0 compatibility. 

Take a look at Chapter 1, "Predefined Symbols," of this book for a 
definition of these variables. 



Masm 5.0 and 5.1 Enhancements 

Turbo Assembler has all the extensions Masm 5.0 and 5.1 have over MASM 
4.0. If you are not familiar with these extensions, here's a list of where to 
look for some of the more important topics: 

■ 80386 Support: See "The 80386" in Chapter 11 of the User's Guide. 

u Simplified Segmentation Directives: See "Simplified Segment Directives 
and 80386 Segment Types" in Chapter 11 of the User' Guide. 

■ String Equates: See "Using Equate Substitutions" in Chapter 5 of the 
User's Guide. 
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■ RETF and RETN Instructions: See "How Subroutines Work" in Chapter 
4 of the User's Guide. 

■ Communal Variables: See the COMM directive in Chapter 3 in this 
book. 

■ Explicitly Including Library Files: See the INCLUDELIB directive in 
Chapter 3 in this book. 

□ More Flexible Structure Definitions: See "Structures and Unions" in 
Chapter 11 of the User's Guide. 

■ Predefined Variables: See "Simplified Segment Directives" in Chapter 4 
and also Chapter 10 of the User's Guide. 



Improved SHL and SHR Handling 

When you use SHL and SHR as part of an arithmetic expression, MASM 
does not permit the shift count to be negative. Turbo Assembler accepts 
negative shift counts and performs the opposite type of shift. For example, 
16 SHL -2 is equivalent to 16 SHR 2. 
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D 



Turbo Assembler Utilities 



Turbo Assembler provides five powerful stand-alone utilities. You can use 
these stand-alone utilities with your Turbo Assembler files, as well as with 
your other modules. 

These highly useful adjuncts to Turbo Assembler are 

■ MAKE (including the TOUCH utility; the stand-alone program manager 
(MAKE) 

■ TLINK (the Turbo Linker) 

■ TLIB (the Turbo Librarian) 

■ GREP (a file-search utility) 

■ OBJXREF (an object module cross-referencer) 
B TCREF (a cross-reference utility) 

This appendix explains what each utility is and illustrates, with code and 
command-line examples, how to use them. 

The Stand- Alone MAKE Utility 

Turbo Assembler places a great deal of power and flexibility at your 
fingertips. You can use it to manage large, complex programs that are built 
from numerous source and object files. Unfortunately, that same freedom 
requires that you remember which files are required to produce other files. 
Why? Because if you make a change in one file, you must then do all the 
necessary recompilation and linking. One solution, of course, is simply to 
recompile everything each time you make a change — ^but as your program 
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grows in size, that becomes more and more time consuming. So what do 
you do? 

The answer is simple: You use MAKE. Turbo Assembler's MAKE is an 
intelligent program manager that — given the proper instructions — does all 
the work necessary to keep your program up-to-date. In fact, MAKE can do 
far more than that. It can make backups, pull files out of different sub- 
directories, and even automatically run your programs should the data files 
that they use be modified. As you use MAKE more and more, you'll see 
new and different ways it can help you to manage your program 
development. 

In this section, we describe how to use stand-alone MAKE with Turbo 
Assembler and TLINK. 



A Quick Example 

Let's start with an example to illustrate MAKE's usefulness. Suppose 
you're writing some programs to help you display information about 
nearby star systems. You have one program — GETSTARS — that reads in a 
text file listing star systems, does some processing on it, then produces a 
binary data file with the resulting information in it. 

GETSTARS uses certain definitions, stored in STARDEFS.INC, and certain 
routines, stored in STARLIB.ASM (and declared in STARLIB.INC). In 
addition, the program GETSTARS itself is broken up into three files: 

■ GSPARSE.ASM 

■ GSCOMP.ASM 

■ GETSTARS.ASM 

The first two files, GSPARSE and GSCOMP, have corresponding include 
files (GSPARSE.INC and GSCOMP.INC). The third file, GETSTARS.ASM, 
has the main body of the program. Of the three files, only GSCOMP.ASM 
and GETSTARS.ASM make use of the STARLIB routines. 

Here are the include files needed by each assembler file: 
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.ASM File Include File(s) 



STARLIB.ASM None 

GSPARSE.ASM STARDEFS.INC 

GSCOMP.ASM STARDEFS.INC,STARLIB.INC 

GETSTARS.ASM STARDEFS.INC,STARLIB.INC,GSPARSE.INC, 

GSCOMP.INC 

To produce GETSTARS.EXE (assuming a medium data model), you would 
enter the following command lines: 

tasra /t /ml /s starlib 

tasm /t /ml /s gsparse 

tasm /t /ml /s gscomp 

tasm /t /ml /s getstars 

tlink starlib gsparse gscomp getstars, getstars, getstars, lib\math lib\io 

Looking at the preceding information, you can see some file dependencies. 

■ GSPARSE, GSCOMP, and GETSTARS all depend on STARDEFS.INC; in 
other words, if you make any changes to STARDEFS.INC, then you'll 
have to recompile all three. 

■ Likewise, any changes to STARLIB.INC will require GSCOMP and GET- 
STARS to be recompiled. 

B Changes to GSPARSE .EsJC means GETSTARS will have to be recompiled; 
the same is true of GSCOMP.INC. 

■ Of course, any changes to any source code file (such as STARLIB.ASM 
and GSPARSE.ASM) means that file must be recompiled. 

■ Finally, if any recompiling is done, then the link has to be done again. 

Quite a bit to keep track of, isn't it? What happens if you make a change to 
STARLIB.INC, recompile GETSTARS.ASM, but forget to recompile 
GSCOMP.ASM? You could make a .BAT file to do the four compilations 
and the one linkage given previously, but you'd have to do them every 
time you made a change. Let's see how MAKE can simpUfy things for you. 



Creating a Makefile 

A makefile is just a combination of the two lists just given: dependencies 
and the commands needed to satisfy them. 

For example, lef s take the Hsts given, combine them, massage them a little, 
and produce the following: 
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getstars.exe: getstars.obj gscomp.obj gsparse.obj starlib.obj 
tlink starlib gsparse gscomp getstars, getstars, \ 
getstars, lib\math lib\io 

getstars.obj: getstars. asm stardefs.inc starlib. inc gscomp. inc gsparse. inc 
tasm /t /ml /s getstars. asm 

gscomp.obj: gscomp. asm stardefs.inc starlib. inc 
tasm /t /ml /s gscomp. asm 

gsparse.obj: gsparse. asm stardefs.inc 
tasm /t /ml /s gsparse. asm 

starlib.obj: starlib. asm 
tasm /t /ml /s starlib. asm 

This just restates what was said before, but with the order reversed some- 
what. Here's how MAKE interprets this file: 

■ The file GETSTARS.EXE depends on four files: GETSTARS.OBJ, 
GSCOMP.OBJ, GSPARSE.OBJ, and STARLIB.OBJ. If any of those four 
change, then GETSTARS.EXE must be updated. How? By using the 
TLINK command given. 

■ The file GETSTARS.OBJ depends on five files: GETSTARS. ASM, 
STARDEFS.INC, STARLIB.INC, GSCOMP.INC, and GSPARSE.INC. If 
any of those files change, then GETSTARS.OBJ must be recompiled by 
using the TASM command given. 

■ The file GSCOMP.OBJ depends on three files: GSCOMP. ASM, 
STARDEFS.INC, and STARLIB.INC. If any of those three change, 
GSCOMP.OBJ must be recompiled using the TASM command given. 

■ The file GSPARSE.OBJ depends on two files: GSPARSE.OBJ and 
STARDEFS.INC. It must be recompiled using the TASM command given 
if either of those files change. 

■ The file STARLIB.OBJ depends on only one file, STARLIB.ASM. It must 
be recompiled via TASM if STARLIB.ASM changes. 

What do you do with this? Type it into a file, which (for now) we'll call 
MAKEHLE. You're then ready to use MAKE.EXE. 



Using a Makefile 

Assuming you've created MAKEFILE like the one we've described 
here — and, of course, assuming that the source code files exist — then all 
you have to do is type the command 

make 
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MAKE looks for MAKEFILE (you can call it something else; we'll talk 
about that later) and reads in the first line, describing the dependencies of 
GETSTARS.EXE. It checks to see if GETSTARS.EXE exists and is up-to-date. 

This requires that it check the same thing about each of the files upon 
which GETSTARS.EXE depends: GETSTARS.OBJ, GSCOMP.OBJ, 
GSPARSE.OBJ, and STARLIB.OBJ. Each of those files depends, in turn, on 
other files, which must also be checked. The various calls to TASM are 
n:\ade as needed to update the .OBJ files, ending with the execution of the 
TLINK command (if necessary) to create an up-to-date version of 
GETSTARS.EXE. 

What if GETSTARS.EXE and all the .OBJ files already exist? In that case, 
MAKE compares the time and date of the last modification of each .OBJ file 
with the time and date of its dependencies. If any of the dependency files 
are more recent than the .OBJ file, MAKE knows that changes have been 
made since the last time the .OBJ file was created and executes the TASM 
command. 

If MAKE does update any of the .OBJ files, then when it compares the time 
and date of GETSTARS.EXE with them, it sees that it must execute the 
TLINK command to make an updated version of GETSTARS.EXE. 

Stepping Through 

Here's a step-by-step example to help clarify the previous description. 
Suppose that GETSTARS.EXE and all the .OBJ files exist, and that 
GETSTARS.EXE is more recent than any of the .OBJ files, and, likewise, 
each .OBJ file is more recent than any of its dependencies. 

If you then enter the command 

make 

nothing happens, since there is no need to update anything. 

Now, suppose that you modify STARLIB.ASM and STARLIB.INC, 
changing, say, the value of some constant. When you enter the command 

make 

MAKE sees that STARLIB.ASM is more recent than STARLIB.OBJ, so it 
issues the command 

tasm /t /ml /s starlib.asm 

It then sees that STARLIB.INC is more recent than GSCOMP.OBJ, so it 
issues the command 
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tasm It /ml /s gscomp.asm 

STARLIB.INC is also more recent than GETSTARS.OBJ, so the next 
command is 

tasm /t /ml /s getstars.asm 

Because of these three commands, the files STARLIB.OBJ, GSCOMP.OBJ, 
and GETSTARS.OBJ are all more recent than GETSTARS.EXE, so the final 
command issued by MAKE is 

tlink starlib gsparse gscomp getstars, getstars, getstars, 
lib\math lib\io 

which links everything together and creates a new version of 
GETSTARS.EXE. (Note that this TLINK command line must actually be one 
line.) 

You have a good idea of the basics of MAKE: what if s for, how to create a 
makefile, and how MAKE interprets that file. Now let's look at MAKE in 
more detail. 



Creating Makefiles 



A makefile contains the definitions and relationships needed to help MAKE 
keep your program(s) up-to-date. You can create as many makefiles as you 
want and name them whatever you. want; MAKEFILE is just the default 
name that MAKE looks for if you don't specify a makefile when you run 
MAKE. 

All rules, definitions, and directives end with a new line; if a Hne is too long 
(such as the TLINK command in the previous example), you can continue it 
to the next line by placing a backslash (\) as the last character on the line. 

Whitespace — ^blanks and tabs — is used to separate adjacent identifiers (such 
as dependencies) and to indent commands within a rule. 



Components of a Makefile 

Creating a makefile is almost like writing a program with definitions, 
commands, and directives. Here's a list of the constructs allowed in a 
makefile: 
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■ comments 

B explicit rules 

■ implicit rules 

■ macro definitions 

■ directives — file inclusion, conditional execution, error detection, macro 
undefinition 

Let's look at each of these in more detail. 



Comments 

Comments begin with a sharp (#) character; the rest of the line following 
the # is ignored by MAKE. Comments can be placed anywhere and never 
have to start in a particular column. 

A backslash (\) wiU not continue a comment onto the next line; instead, you 
must use a # on each line. In fact, you cannot use a backslash as a continu- 
ation character in a line that has a comment. If it precedes the #, it is no 
longer the last character on the line; if it follows the #, then it is part of the 
comment itself. 

Here are some examples of comments in a makefile: 

# makefile for GETSTARS.EXE 

# does complete project maintenance 

getstars.exe: getstars.obj gscomp.obj gsparse.obj starlib.obj 

# can't put a comment at the end of the next line 

tlink starlib gsparse gscomp getstars, getstars,\ 
getstars, lib\math lib\io 

# legal comment 

# can't put a comment between the next two lines 

getstars.obj: getstars. asm stardefs.inc starlib. inc gscomp. inc gsparse. inc 
tasm /t /ml /s getstars. asm # you can put a comment here 

Explicit Rules 

You are already familiar with explicit rules, since those are what you used 
in the makefile example given earlier. Explicit rules take the form 

target [target ... ]: [source source ... ] 
[command] 
[command] 

where target is the file to be updated, source is a file upon which target 
depends, and command is any valid MS-DOS command (including 
invocation of .BAT files and execution of .COM and .EXE files). 
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Explicit rules define one or more target names, zero or more source files, 
and an optional list of commands to be performed. Target and source-file 
names listed in explicit rules can contain normal MS-DOS drive and 
directory specifications, but they cannot contain wildcards. 

Syntax here is important, target must be at the start of a line (in column 1), 
where each command must be indented (must be preceded by at least one 
blank or tab). As mentioned before, the backslash (\) can be used as a 
continuation character if the list of source files or a given command is too 
long for one line. Finally, both the source files and the commands are 
optional; it is possible to have an explicit rule consisting only of target 
[target ...] followed by a colon. 

The idea behind an explicit rule is that the command or commands listed 
will create or update target, usually using the source files. When MAKE 
encounters an explicit rule, it first checks to see if any of the source files are 
themselves target files elsewhere in the makefile. If so, then those rules are 
evaluated first. 

Once all the source files have been created or updated based on other 
explicit (or implicit) rules, MAKE checks to see if target exists. If not, each 
command is invoked in the order given. If target does exist, its time and date 
of last modification are compared against the time and date for each source. 
If any source has been modified more recently than target, the list of 
commands is executed. 

A given file name can occur on the left side of an explicit rule only once in a 
given execution of MAKE. 

Each command line in an explicit rule begins with whitespace. MAKE 
considers all lines following an explicit rule to be part of the conunand list 
for that rule, up to the next line that begins in column 1 (without any 
preceding whitespace) or to the end of the file. Blank lines are ignored. 

Special Considerations 

An explicit rule with no command lines following it is treated a little 
differently than an explicit rule with command lines. 

■ If an explicit rule exists for a target with commands, the only files that the 
target depends on are the ones listed in the explicit rule. 

■ If an explicit rule has no commands, the targets depend on the files given 
in the explicit rule, and they also depend on any file that matches an 
implicit rule for the target(s). 

See the following section for a discussion of implicit rules. 
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Here are some examples of explicit rules: 

myprog.obj: myprog.asm 
tasm /t myprog.asm 

prog2.obj : prog2.asm include\stdio.inc 
tasm It /ml prog2.asm 

prog.exe: myprog.asm prog2.asm include\stdio.inc 
tasm /t myprog.asm 
tasm /t /ml prog2.asm 
tlink myprog prog2, prog, , lib\io 

■ The first explicit rule states that MYPROG.OBJ depends upon 
MYPROG.ASM, and that MYPROG.OBJ is created by executing the given 
TASM command. 

■ Similarly, the second rule states that PR0G2.0BJ depends upon 
PROG2.ASM and STDIO.INC (in the INCLUDE subdirectory) and is 
created by the TASM command. 

■ The last rule states that PROG.EXE depends on MYPROG.ASM, 
PROG2.ASM, and STDIO.INC, and that should any of the three change, 
PROG.EXE can be rebuilt by the series of commands given. However, 
this may create unnecessary work because, even if only MYPROG.ASM 
changes, PROG2.ASM will still be recompiled. This occurs because all of 
the commands under a rule will be executed as soon as that rule's target 
is out of date. 

■ If you place the explicit rule 

prog.exe: myprog.obj prog2.obj 

tlink myprog prog2, prog, , lib\io 

as the first rule in a makefile and follow it with the rules given (for 
MYPROG.OBJ and PR0G2.0BJ), only those files that need to be re- 
compiled will be. 

Implicit Rules 

MAKE allows you to define implicit rules as well. Implicit rules are 
generalizations of explicit rules. What do we mean by that? 

Here's an example that illustrates the relationship between the two types of 
rules. Consider this explicit rule from the previous sample program: 

starlib.obj: starlib.asm 
tasm /t /ml /s starlib.asm 

This rule is a common one because it follows a general principle: An .OBJ 
file is dependent on the .ASM file with the same file name and is created by 
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executing TASM. In fact, you might have a makefile where you have 
several (or even several dozen) explicit rules following this same format. 

By redefining the explicit rule as an implicit rule, you can eliminate aU the 
explicit rules of the same form. As an implicit rule, it would look like this: 

.asm.obj: 

tasm /t /ml /s $< 

This rule means, "Any file ending with .OBJ depends on the file with the 
same name that ends in .ASM, and the .OBJ file is created using the 
command 

tasm /t /ml /s $< 

where $< represents the file's name with the source (.ASM) extension." 
(The symbol $< is a special macro and is discussed in the next section.) 

The syntax for an implicit rule is 

. source_extension .target_extension: 
{command] 
[command] 

where, as before, the commands are optional and must be indented. 

The source_extension (which must begin in column 1) is the extension of the 
source file; that is, it applies to any fUe having the format 

f name . sou rce_extens ion 

Likewise, the targetjextension refers to the the file 

f name. target_extens ion 

where fname is the same for both files. In other words, this implicit rule 
replaces all explicit rules having the format 

fname.target_extension: fname . source_extens ion 
{ command] 
[command] 

(or any fname. 

ImpUcit rules are used if no explicit rule for a given target can be found, or 
if an explicit rule with no commands exists for the target. 

The extension of the file name in question is used to determine which 
implicit rule to use. The implicit rule is applied if a file is found with the 
same name as the target, but with the mentioned source extension. 
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For example, suppose you had a makefile (named MAKEFILE) whose 
contents were 

.asm.obj: 

tasm /t /ml /s $< 

If you had an assembler program named RATIO.ASM that you wanted to 
compile to RATIO.OBJ, you could use the command 

make ratio. obj 

MAKE would take RATIO.OBJ to be the target. Since there is no explicit 
rule for creating RATIO.OBJ, MAKE applies the implicit rule and generates 
the command 

tasm /t /ml /s ratio. asm 

which, of course, does the compile step necessary to create RATIO.OBJ. 

Implicit rules are also used if an explicit rule is given with no commands. 
Suppose, as mentioned before, you had the following implicit rule at the 
start of your makefile: 

.asm.obj: 

tasm /t /ml /s $< 

You could then rewrite the last several explicit rules as follows: 

getstars.obj: stardefs.inc starlib.inc gscomp.inc gsparse.inc 
gscomp.obj: stardefs.inc starlib.inc 
gsparse.obj: stardefs.inc 

Since you don't have explicit information on how to create these .OBJ files, 
MAKE applies the implicit rule defined earlier. And since STARLIB.OBJ 
depends only on STARLIB.ASM, that rule was dropped altogether from 
this list; MAKE automatically applies it. 

Several implicit rules can be written with the same target extension, but 
only one such rule can apply at a time. If more than one implicit rule exists 
for a given target extension, each rule is checked in the order the rules 
appear in the makefile, until all applicable rules are checked. 

MAKE uses the first implicit rule that discovers a file with the source 
extension. Even if the commands of that rule fail, no more implicit rules are 
checked. 

All lines following an implicit rule are considered to be part of the 
command list for the rule, up to the next line that begins without white- 
space or to the end of the file. Blank lines are ignored. The syntax for a 
command line is provided later in this chapter. 
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Special Considerations 

Unlike explicit rules, MAKE does not know the full file name with an 
implicit rule. For that reason, special macros are provided with MAKE that 
allow you to include the name of the file being built by the rule. (See the 
discussion of macro definitions in this section for details.) 

Examples 

Here are some examples of implicit rules: 

.c.obj: 
tec -c $< 

.asm.obj: 

tasm $* /mx; 

In the first implicit rule example, the target files are .OBJ files and their 
source files are .C files. This example has one command line in the 
command list; command-line syntax is covered later in this section. 

The second example directs MAKE to assemble a given file from its .ASM 
source file, using TASM with the /MX option. 

Command Lists 

We've talked about both explicit and implicit rules and how they can have 
Hsts of commands. Let's talk about those commands and your options for 
setting them up. 

Commands in a command list must be indented — that is, preceded by at 
least one blank or tab — and take the form 

[ prefix ... ] command_body 

Each comnnand line in a command list consists of an (optional) list of 
prefixes, followed by a single command body. 

Prefix 

The prefixes allowed in a command modify the treatment of these 
commands by MAKE. The prefix is either the at (@) symbol or a hyphen (-) 
followed immediately by a number. 
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@ Forces MAKE to not display the command before executing it. 

The display is hidden even if the -s option was not given on the 
MAKE command line. This prefix applies only to the command 
on which it appears. 

-num Affects how MAKE treats exit codes. If a number {num) is 
provided, then MAKE will abort processing only if the exit 
status exceeds the number given. In this example, MAKE will 
abort only if the exit status exceeds 4: 

-4 myprog sample. x 

If no -num prefix is given, MAKE checks the exit status for the 
command. If the status is nonzero, MAKE wUl stop and delete 
the current target file. 

With a hyphen but no number, MAKE wUl not check the exit 
status at aU. Regardless of what the exit status was, MAKE will 
continue. 

Command Body 

The command body is treated exactly as it would be if it were entered as a 
line to COMMAND.COM, with the exception that redirection and pipes are 
not supported. 

MAKE executes the following built-in commands by invoking a copy of 
COMMAND.COM to perform them: 



BREAK 


CD 


CHDIR 


CLS 


COPY 


CTTY 


DATE 


DEL 


DIR 


ERASE 


MD 


MKDIR 


PATH 


PROMPT 


REN 


RENAME 


SET 


TIME 


TYPE 


VER 


VERIFY 


VOL 









MAKE searches for any other command name using the MS-DOS search 
algorithm: 

■ The current directory is searched first, followed by each directory in the 
path. 

B In each directory, first a file with the extension .COM is checked, then an 
•EXE, and finally a .BAT. 

a If a .BAT file is found, a copy of COMMAND.COM is invoked to execute 
the batch file. 

Obviously, if an extension is supplied in the command line, MAKE searches 
only for that extension. 
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Examples 

This command will cause COMMAND.COM to execute the command: 

cd c:\include 
This command will be searched for using the full search algorithm: 

tlink X y,z,z,lib\io 
This command will be searched for using only the .COM extension: 

myprog.com geo.xyz 
This command will be executed using the explicit file name provided: 

c:\myprogs\fil.exe -r 

Macros 

Often certain commands, file names, or options are used again and again in 
your makefile. In the examples at the start of this appendix, all the TASM 
commands looked for the source in the current directory. Suppose you 
wanted to control which subdirectories the source files came from and 
where the output is placed. You could go through and modify each line of 
your makefile everytime you change these, or you could define macros to 
semi-automate the process. 

A macro is a name that represents some string of characters. A macro 
definition gives a macro name and the expansion text; thereafter, when 
MAKE encounters the macro name, it replaces the name with the 
expansion text. 

Suppose you define the following macros at the start of your makefile: 

SRC = C:\ASM\ 
OUT = OBJS\ 
INC = C:\INC\ 

Now, if the rest of your makefile is 

getstars.exe: $(OUT)getstars.obj $(OUT)gsparse \ 
$ (OUT) gscomp.ob j $ (OUT) starlib.ob j 
tlink $(OUT)starlib $(OUT)gsparse $(OUT)gscomp $(OUT)getstart, \ 
$(OUT)getstars, $(OUT)getstars, lib\math lib\io 

getstars.obj: $(SRC)getstars.asm $(INC) stardefs.inc \ 
$(INC)starlib.inc $(INC)gscomp.inc \ 
$(INC)gsparse.inc 
tasm /t /ml /s /i$(INC) $(SRC)getstars.asm, $ (OUT) getstars.obj 
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gscomp.obj: $(SRC) gscomp.asm $(INC)stardefs.inc $(INC) starlib.inc 
tasm /t /ml /s /i$(INC) $ (SRC) gscomp.asm, $ (OUT) gscomp.obj 

gsparse.obj: $(SRC)gsparse.asm $(INC) stardefs.inc $ (INC) starlib.inc 
tasm /t /ml /s /i$(INC) $(SRC)gsparse.asm, $ (OUT) gsparse.obj 

starlib.obj: $(SRC) starlib.asm 

tasm /t /ml /s /i$(INC) $ (SRC) starlib.asm, $ (OUT) starlib.obj 

When you run MAKE, $(SRC) is replaced with the expansion text C:\ 
ASM\, $(INC) is replaced with the expansion text C:\INC\, and $(OUT) is 
replaced with the expansion text OBJS\. 

So, what have you gained? Flexibility. By changing any one of the macros, 
you have changed all the commands that depend on that macro. For 
instance, suppose you decide to move the include files to a new subdirec- 
tory called C:\INC\STAR. All you have to do to update the makefile is 
change the INC macro to 

INC = C:\INC\STAR\ 

and you've changed all the commands to use this new include sub- 
directory. 

Defining Macros 

Macro definitions take the form 

mac[o_name=expansion text 

where macrojiame is the name of the macro: A string of letters and digits 
with no whitespace in it, though you can have whitespace between 
macrojiame and the equal sign (=). The expansion text is any arbitrary string 
containing letters, digits, whitespace, and punctuation; it is ended by 
newline. 

If macrojiame has previously been defined, either by a macro definition in 
the makefile or by the -D option on the MAKE command line, the new 
definition replaces the old. 

Case is significant in macros; that is, the macros named mdl, Mdl, and 
MDL are all considered different. 

Using Macros 

Macros are invoked in your makefile with the format 

$ (macro_name) 

The parentheses are required for all invocations, even if the macro name is 
just one character long, with the exception of three special predefined 
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macros that we'll talk about soon. This construct — $(macro_name) — is 
known as a macro invocation. 

When MAKE encounters a macro invocation, it replaces the invocation 
with the macro's expansion text. If the macro is not defined, MAKE 
replaces it with the null string. 

Special Considerations 

Macros in macros: Macro cannot be invoked on the left {macrojtame) side 
of a macro definition. They can be used on the right (expansion text) side, 
but they are not expanded until the macro being defined is invoked. In 
other words, when a macro invocation is expanded, any macros embedded 
in its expansion text are also expanded. 

Macros in rules: Macro invocations are expanded immediately in rule 
lines. 

Macros in directives: Macro invocations are expanded immediately in !if 
and !elif directives. If the macro being invoked in an !if or !elif directive is 
not currently defined, it is expanded to the value (FALSE). 

Macros in commands: Macro invocations in commands are expanded 
when the connmand is executed. 

Predefined Macros 

MAKE comes with several special macros built in: $d, $*, $<, $:, $., and $&. 
The first is a defined test macro used in the conditional directives !if and 
!elif; the others are file name macros used in explicit and implicit rules. In 
addition, the current SET environment strings are automatically loaded as 
macros, and the macro __MAKE is defined to be 1 (one). 

Defined Test Macro ($d) The defined test macro $d expands to 1 if the 
given macro name is defined, or to if it is not. The content of the macro's 
expansion text does not matter. This special macro is allowed only in !if and 
!elif directives. 
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For example, suppose you wanted to modify your makefile so that it would 
use the medium memory model if you didn't specify one, you could put 
this at the start of your makefile: 

!if !$d(INC) f if INC is not defined 
INC=C:\INC\ I define the default path 

lendif 

If you invoke MAKE with the command line 

make -DINC=C:\INC\STAR\ 

then INC is defined as C:\INC\STAR\. If, however, you just invoke MAKE 
by itself, 

make 

then INC is defined as CADSJCX, your "default" memory model. 

Various File Name Macros The various file name macros work in similar 
ways, expanding to some variation of the full path name of the file being 
bmlt. 

Base File Name Macro ($*) 

The base file name macro is allowed in the commands for an explicit or an 
implicit rule. This macro ($*) expands to the file name being built, exclud- 
ing any extension, like this: 

File name is A:\P\TESTFILE.ASM 
$* expands to A:\P\TESTFILE 

For example, you could modify the explicit GETSTARS.EXE rule already 
given to look like this: 

getstars.exe: getstars.obj gscomp.obj gsparse.obj starlib.obj 
tlink starlib gsparse gscomp $*, $*, $*, \ 
lib\emu lib\math lib\io 

When the command in this rule is executed, the macro $* is replaced by the 
target file name (sans extension), getstars. For implicit rules, this macro is 
very useful. 

For example, an implicit rule for TASM might look like this: 

.asm.obj: 
tasm /t $* 

Full File Name Macro ($<) 

The full file name macro ($<) is also used in the commands for an explicit 
or implicit rule. In an explicit rule, $< expands to the full target file name 
(including extension), like this: 
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File name is A:\P\TESTFILE.ASM 
$< expands to A:\P\TESTFILE.ASM 

For example, the rule 

starlib.obj: starlib.asm 
copy $< \oldobjs 
tasm /t $* 

will copy STARLIB.OBJ to the directory \OLDOBJS before compiling 
STARLIB.ASM. 

In an implicit rule, $< takes on the file name plus the source extension. For 
example, the previous implicit rule 

.obj.asm: 

tasm /t $*.asm 

can be rewritten as 

.obj.asm: 
tasm /t $< 

File Name Path Macro ($:) This macro expands to the path name (without 
the file name), like this: 

File name is A:\P\TESTFILE.ASM 
$: expands to A:\P\ 

File Name and Extension Macro ($.) This macro expands to the file name, 
with extension, like this: 

File name is A:\P\TESTFILE.ASM 
$. expands to TESTFILE.ASM 

File Name Only Macro ($&) This macro expands to the file name only, 
without path or extension, like this: 

File name is A:\P\TESTFILE.ASM 
$S expands to TESTFILE 



Directives 

Turbo Assembler's MAKE allows something that other versions of MAKE 
don't: directives similiar to those allowed for assembler itself. You can use 
these directives to include other makefiles, to make the rules and com- 
mands conditional, to print out error messages, and to "undefine" macros. 

Directives in a makefile begin with an exclamation point (!) as the first 
character of the line, unlike assembler, which uses the sharp character (#). 
Here is the complete list of MAKE directives: 
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'.include 

!if 

!else 

!elif 

iendif 

! error 

lundef 

File-Inclusion Directive 

A file-inclusion directive (linclude) specifies a file to be included into the 
makefile for interpretation at the point of the directive. It takes this form: 

'.include " filename " 

These directives can be nested arbitrarily deep. If an include directive 
attempts to include a file that has already been included in some outer level 
of nesting (so that a nesting loop is about to start), the inner include 
directive is rejected as an error. 

How do you use this directive? Suppose you created the file MODEL.MAC, 
which contained the following: 

!if !$d(MDL) 

MDL=medium 

iendif 

You could then make use of this conditional macro definition in any 
makefile by including the directive 

linclude "MODEL.MAC" 

When MAKE encounters the linclude directive, it opens the specified file 
and reads the contents as if they were in the makefile itself. 

Conditional Directives 

Conditional directives (!if, ielif, !else, and Iendif) give a programmer a 
measure of flexibility in constructing makefiles. Rules and macros can be 
conditionalized so that a command-line macro definition (using the -D 
option) can enable or disable sections of the makefile. 

The format of these directives parallels that of the assembler preprocessor: 

!if expression 

[ lines ] 
Iendif 

!if expression 

[ lines ] 
[else 



Appendix D. Turbo Assembler Utilities 201 



[ lines ] 
lendif 

!if expression 

[ lines ] 
!elif expression 

[ lines ] 
lendif 

Note: [lines] can be any of the following: 

macro_definition 

explicit_rule 

implicit_rule 

include_directive 

if_group 

error_directive 

undef_directive 

The conditional directives form a group, with at least an !if directive 
beginning the group and an lendif directive closing the group. 

■ One !else directive can appear in the group. 

■ !elif directives can appear between the !if and any lelse directives. 

■ Rules, macros, and other directives can appear between the various 
conditional directives in any number. Note that complete rules with their 
commands cannot be split across conditional directives. 

■ Conditional directive groups can be nested arbitrarily deep. 

Any rules, commands, or directives must be complete within a single 
source file. 

Any !if directives must have matching lendif directives within the same 
source file. Thus the following include file is illegal, regardless of what is 
contained in any file that might include it because it does not have a 
matching lendif directive: 

!if $(FILE_COUNT) > 5 

some rules 
!else 

other rules 
<end-of-file> 

Expressions Allowed in Conditional Directives 

The expression allowed in an !if or an !elif directive uses a assembler-like 
syntax. The expression is evaluated as a simple 32-bit signed integer 
expression. 

Numbers can be entered as decimal, octal, or hexadecimal constants. For 
example, these are legal constants in an expression: 
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4536 # decimal constant 
0677 i octal constant 
0x23aF S hexadecimal constant 

An expression can use any of the following unary operators: 

- negation 

bit complement 
! logical not 

An expression can use any of the following binary operators: 

+ addition 

- subtraction 

* multiplication 

/ division 

% remainder 

» right shift 

« left shift 

& bitwise and 

I bitwise or 

^ bitwise exclusive or 

&& logical and 

I I logical or 

> greater than 

< less than 

>= greater than or equal 

<= less than or equal 

== equality 

!= inequality 

An expression can contain the following ternary operator: 

? : The operand before the ? is treated as a test. 

If the value of that operand is nonzero, then the second operand 
(the part between the ? and :) is the result. If the value of the first 
operand is zero, the value of the result is the value of the third 
operand (the part after the :). 

Parentheses can be used to group operands in an expression. In the absence 
of parentheses, binary operators are grouped according to the same 
precedence given in assembler. 

As in assembler, for operators of equal precedence, grouping is from left to 
right, except for the ternary operator (? :), which is right to left. 

Macros can be invoked within an expression, and the special macro $d() is 
recognized. After all macros have been expanded, the expression must 
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have proper syntax. Any words in the expanded expression are treated as 
errors. 

Error Directive 

The error directive (lerror) causes MAKE to stop and print a fatal 
diagnostic containing the text after ierror. It takes the format 

.'error any_text 

This directive is designed to be included in conditional directives to allow a 
user-defined condition. For example, you could insert the following code in 
front of the first explicit rule: 

.'if !$d(MDL) 

i if MDL is not defined 

lerror MDL not defined 

.'endif 

If you reach this spot without having defined MDL, then MAKE wiU stop 
with this error message: 

Fatal makefile 5: Error directive: MDL not defined 

Undef Directive 

The undefine directive (.'undef ) causes any definition for the named macro 
to be forgotten. If the macro is currently tmdefined, this directive has no 
effect. The syntax follows: 

! undef macro name 



Using MAKE 



You now know a lot about how to write makefiles; now's the time to learn 
how to use them with MAKE. 



Command-Line Syntax 

The simplest way to use MAKE is to type the command 

make 

at the MS-DOS prompt. MAKE then looks for MAKEHLE; if it can't find it, 
it looks for MAKEFILE.MAK; if it can't find that, it halts with an error 
message. 
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What if you want to use a file with a name other than MAKEFILE or 
MAKEHLE.MAK? You give MAKE the file option (-f), like this: 

make -f stars. mak 

The general sjmtax for MAKE is 

make option option ... target target ... 

where option is a MAKE option (discussed later), and target is the name of a 
target file to be handled by explicit rules. 

Here are the syntax rules: 

B The word make is followed by a space, then a list of make options. 

B Each make option must be separated from its adjacent options by a space. 
Options can be placed in any order, and any number of these options can 
be entered (as long as there is room in the command line). 

B After the list of make options comes a space, then an optional list of 
targets. 

B Each target must also be separated from its adjacent targets by a space. 
MAKE evaluates the target files in the order listed, recompiling their 
constituents as necessary. 

If the command line does not include any target names, MAKE uses the 
first target file mentioned in an explicit rule. If one or more targets are 
mentioned on the command Une, they will be built as necessary. 

Here are some more examples of MAKE command lines: 

make -n -f stars. mak 

make -s 

make -linclude -DMDL = compact 



A Note About Stopping MAKE 

MAKE wiU stop if any command it has executed is aborted via a Ctrl Break. 
Thus, a Ctrl-C will stop the currently executing command and MAKE as 
well. 



The BUILTINS.MAK File 

When using MAKE, you will often find that there are macros and rules 
(usually implicit ones) that you use again and again. You've got three ways 
of handling them. First, you can put them in each and every makefile you 
create. Second, you can put them all in one file and use the linclude 



Appendix D. Turbo Assembler Utilities 205 



directive in each makefile you create. Third, you can put them all in a file 
named BUILTINS.MAK. 

Each time you run MAKE, it looks for a file named BUILTINS.MAK; if it 
finds the file, MAKE reads in it before handling MAKEFILE (or whichever 
makefile you want it to process). 

The BUILTINS.MAK file is intended for any rules (usually implicit rules) or 
macros that will be commonly used in files anywhere on your computer. 

There is no requirement that any BUILTINS.MAK file exist. If MAKE finds 
a BUILTINS.MAK file, it interprets that file first. If MAKE cannot find a 
BUILTINS.MAK file, it proceeds directly to interpreting MAKEFILE (or 
whatever makefile you specify). 



How MAKE Searches for Makefiles 

MAKE will search for BUILTINS.MAK in the current directory or any 
directory in the path. You should place this file in the same directory as the 
MAKE.EXE file. 

MAKE always searches for the makefile in the current directory only. This 
file contains the rules for the particular executable program file being built. 
The two files have identical syntax rules. 

MAKE also searches for any linclude files in the current directory. If you 
use the -I (Include) option, it will also search in the specified directory. 



The TOUCH Utility 

There are times when you want to force a particular target file to be 
recompiled or rebuilt, even though no changes have been made to its 
sources. One way to do this is to use the TOUCH utility included with 
Turbo Assembler. TOUCH changes the date and time of one or more files to 
the current date and time, making it ''newer" than the files that depend on 
it. 

To force a target file to be rebuilt, touch one of the fUes that target depends 
on. To touch a file (or files), enter 

touch filename [filename ... ] 

at the DOS prompt. TOUCH will then update the file's creation date(s). 

Once you do this, you can invoke MAKE to rebuild the touched target 
fUe(s). (You can use the DOS wildcards * and ? with TOUCH.) 
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MAKE Command-Line Options 

We've alluded to several of MAKE's command-line options; now we'll 
present a complete list of them. Note that case (upper or lower) is 
significant. 

-a Generates an autodependency check. 

-Didentifier Defines the named identifier. 

-Diden=strtng Defines the named identifier iden to the string after the 
equal sign. The string cannot contain any spaces or tabs. 

-Idirectory MAKE will search for include files in the indicated 
directory (as well as in the current directory). 

-^identifier Undefines any previous definitions of the named 
identifier. 

-s Normally, MAKE prints each command as it is about to 

be executed. With the -s option, no commands are 
printed before execution. 

-n Causes MAKE to print the commands, but not actually 

perform them. This is useful for debugging a makefile. 

-ifilename Uses filename as the MAKE file. U filename does not exist, 
and no extension is given, tries FILENAME.MAK. 

-? or -h Prints help message. 

MAKE Error Messages 

MAKE diagnostic messages fall into two classes: fatals and errors. When a 
fatal error occurs, compilation immediately stops. You must take appro- 
priate action and then restart the compilation. Errors will indicate some sort 
of syntax or semantic error in the source makefile. MAKE will complete 
interpreting the makefile and then stop. 



Fatals 

Don't know how to make XXXXXXXX 

This message is issued when MAKE encounters a nonexistent file name in 
the build sequence, and no rule exists that would allow the file name to be 
built. 
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Error directive: XXXX 

This message is issued when MAKE processes an #error directive in the 
source file. The text of the directive is displayed in the message. 

Incorrect command-line argument: XXX 

This error occurs if MAKE is executed with incorrect command-line 
arguments. 

Not enough memory 

This error occurs when the total working storage has been exhausted. You 
should try this on a machine with more memory. If you already have 640K 
in your machine, you may have to simplify the source file. 

Unable to execute command 

This message is issued after a command was to be executed. This could be 
caused because the command file could not be found, or because it was 
misspelled. A less likely possibility is that the command exists but is 
somehow corrupted. 

Unable to open makefile 

This message is issued when the current directory does not contain a file 
named MAKEHLE. 



Errors 

Bad file name format in include statement 

Include file names must be surrounded by quotes or angle brackets. The file 
name was missing the opening quote or angle bracket. 

Bad undef statement syntax 

An lundef statement must contain a single identifier and nothing else as 

the body of the statement. 

Character constant too long 

Character constants can be only one or two characters long. 

Command arguments too long 

The arguments to a command executed by MAKE were more than 127 
characters — a limit imposed by MS-DOS. 

Command S5nitax error 

This message occurs if 

■ The first rule line of the makefile contained any leading whitespace. 

■ An implicit rule did not consist of .ext.ext:. 

B An explicit rule did not contain a name before the : character. 

■ A macro definition did not contain a name before the = character. 
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Division by zero 

A divide or remainder in an !if staten\ent has a zero divisor. 

Expression syntax error in !if statement 

The expression in an !if statement is badly formed — it contains a 
mismatched parenthesis, an extra or missing operator, or a missing or extra 
constant. 

File name too long 

The file name given in an linclude directive was too long for the compiler 
to process. File names in MS-DOS must be no more than 64 characters long. 

Illegal character in constant expression X 

MAKE encountered some character not allowed in a constant expression. If 
the character is a letter, this indicates a (probably) misspelled identifier. 

Illegal octal digit 

An octal constant was found containing a digit of 8 or 9. 

Macro expansion too long 

A macro cannot expand to more than 4,096 characters. This error often 
occurs if a macro recursively expands itself. A macro cannot legally expand 
to itself. 

Misplaced elif statement 

An !elif directive was encountered without any matching !if directive. 

Misplaced else statement 

An !else directive was encountered without any matching !if directive. 

Misplaced endif statement 

An lendif directive was encountered without any matching !if directive. 

No file name ending 

The file name in an include statement was missing the correct closing quote 
or angle bracket. 

Redefinition of target XXXXXXXX 

The named file occurs on the left-hand side of more than one explicit rule. 

Unable to open include file XXXXXXXXX.XXX 

The named file could not be found. This could also be caused if an include 
file included itself. Check whether the named file exists. 

Unexpected end of file in conditional started on line # 

The source file ended before MAKE encountered an lendif. The lendif was 

either missing or misspelled. 

Unknown preprocessor statement 

A ! character was encountered at the beginning of a line, and the statement 
name following was not error, undef, if, elif, include, else, or endif. 
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Turbo Link 



Turbo Link (TLINK) is invoked as a separate program and can also be used 
as a stand-alone linker. 

TLINK is lean and mean; while it lacks some of the bells and whistles of 
other linkers, it is extremely fast and compact. 

In this appendix, we describe how to use TLINK as a stand-alone linker. 



Invoking TLINK 



You can invoke TLINK at the DOS command line by typing tlink with or 
without parameters. 

When invoked without parameters, TLINK displays a summary of 
parameters and options that looks like this: 

Turbo Link Version 2.0 Copyright (c) 1987,1988 Borland International 
The syntax is: TLINK objfiles, exefile, mapfile, libfiles 
@xxxx indicates use response file xxxx 
Options :/ni = map file with publics 

/x = no map file at all 

/i = initialize all segments 

/I = include source line numbers 

/s = detailed map of segments 

/n = no default libraries 

/d = warn if duplicate symbols in libraries 

/c = lowercase significant in symbols 

/3 = enable 32-bit processing 

/v = include full symbolic debug information 

/e = ignore Extended Dictionary 

/t = create COM file 

In TLINK's summary display, the line 

The syntax is: TLINK objfiles, exefile, mapfile, libfiles 

specifies that you supply file names in the given order, separating the file 
types with commas. 

For example, if you supply the command line 

tlink /c mainline wd In tx,fin,mfin,lib\comm lib\support 

TLINK will interpret it to mean that 
■ Case is significant during linking (/c). 
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D The .OBJ files to be linked are MAINLESJE.OBJ, WD.OBJ, LN.OBJ, and 
TX.OBJ. 

B The executable program name will be FIN.EXE. 
B The map file is MFIN.MAP. 

Q The Ubraiy files to be linked in are COMM.LIB and SUPPORT.LIB, both 
of which are in subdirectory LIB. 

TLINK appends extensions to file names that have none: 

D .OBJ for object files 

B .EXE for executable files; .COM for executable files with the /t option 

B .MAP for map files 

B .LIB for library files 

Be aware that where no .EXE file name is specified, TLINK derives the 
name of the executable file by appending .EXE to the first object file name 
listed. If for example, you had not specified FIN as the .EXE file name in the 
previous example, TLINK would have created MAINLINE.EXE as your 
executable file. 

TLINK always generates a map file, unless you explicitly direct it not to by 
including the /x option on the command line. 

B If you give the /m option, the map file includes publics. 

B If you give the /s option, the map file is a detailed segment map. 

These are the rules TLINK follows when determining the name of the map 
file. 

B If no .MAP file is specified, TLINK derives the map file name by adding a 
.MAP extension to the .EXE file name. (The .EXE file name can be given 
on the command line or in the response file; if no .EXE name is given, 
TLINK will derive it from the name of the first .OBJ file.) 

B If a map file name is specified in the command line (or in the response 
file), TLINK adds the .MAP extension to the given name. 

Note that even if you specify a map file name, if the /x option is specified 
then no map file will be created at all. 



Using Response Files 

TLINK lets you supply the various parameters on the command line, in a 
response file, or in any combination of the two. 
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A response file is just a text file that contains the options and /or file names 
that you would usually type in after the name TLINK on your command 
line. 

Unlike the command line, however, a response file can be continued onto 
several lines of text. You can break a long list of object or library files into 
several lines by ending one line with a plus character and continuing the 
list on the next line. 

Also, you can start each of the four components on separate lines: object 
files, executable file, map file, libraries. When you do this, you must leave 
out the comma used to separate components. 

To illustrate these features, suppose that you rewrote the previous 
command-line example as a response file, FINRESP, like this: 

/c mainline wd+ 

In tx,fin+ 

mfin+ 

libXcoinm lib\support 

You would then enter your TLINK command as 

tlink @finresp 

Note that you must precede the file name with an "at" character (@) to 
indicate that the next name is a response file. 

Alternately, you may break your link command into multiple response 
files. For example, you can break the previous command line into the 
following two response files: 



File Name Contents 

LISTOBJS mainline+ 

wd+ 
In tx 

LISTLIBS lib\comm+ 

lib \ support 

You would then enter the TLINK command as 

tlink /c @listobjs,fin,mfin,@listlibs 
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TLINK Options 



TLINK options can occur anywhere on the command line. The options 
consist of a slash (/) followed by the option-specifying letter (m, s, I, i, n, d, 
X, 3, V, e, t, or c). 

If you have more than one option, spaces are not significant (/m/c is the 
same as /m /c), and you can have them appear in different places on the 
command line. The following sections describe each of the options. 



The /x, /m, /s Options 

By default, TLINK always creates a map of the executable file. This default 
map includes only the list of the segments in the program, the program 
start address, and any warning or error messages produced during the link. 
Use the /x option if you don't want to generate a map file at all. 

If you want to create a more complete map, the /m option wUl add a list of 
public symbols to the map file, sorted in increasing address order. This kind 
of map file is useful in debugging. Many debuggers, such as Periscope, can 
use the list of public symbols to allow you to refer to symbolic addresses 
when you are debugging. 

The /s option creates a map file with segments, public symbols and the 
program start address just like the /m option did, but also adds a detailed 
segment map. The following is an example of a detailed segment map: 





Length 










Alignment/ 


Address 


(Bytes) 


Class 


Segment Name 


Group 


Module 


Combining 


0000:0000 


0E5B 


C=CODE 


S=SYMB TEXT 


G=(none) 


M=SYMB.ASM 


ACBP=28 


0OE5:000B 


2735 


C=CODE 


S=QUAL TEXT 


G=(none) 


M=QUAL.ASM 


ACBP=28 


0359:0000 


002B 


C=CODE 


S=SCOPY TEXT 


G=(none) 


M=SCOPY 


ACBP=28 


035B:000B 


003A 


C=CODE 


S=LRSH TEXT 


G=(none) 


M=LRSH 


ACBP=20 


035F:0005 


0083 


C=CODE 


S=PADA TEXT 


G=(none) 


M=PADA 


ACBP=20 


0367:0008 


005B 


C=CODE 


S=PADD TEXT 


G=(none) 


M=PADD 


ACBP=20 


036D:0003 


0025 


C=CODE 


S=PSBP TEXT 


G=(none) 


M=PSBP 


ACBP=20 


036F:0008 


05CE 


C=CODE 


S=BRK TEXT 


G=(none) 


M=BRK 


ACBP=28 


03CC:0006 


066F 


C=CODE 


S=FLOAT TEXT 


G=(none) 


M=FLOAr 


ACBP=20 


0433:0006 


OOOB 


C=DATA 


S= DATA 


G=DGROUP 


M=SYMB.ASM 


ACBP=48 


0433:0012 


00D3 


C=DATA 


S= DATA 


G=DGROUP 


M=QUAL.ASM 


ACBP=48 


0433:00E6 


OOOE 


C=DATA 


S= DATA 


G=DGROUP 


M=BRK 


ACBP=48 


0442:0004 


0004 


C=BSS 


S= BSS 


G=DGROUP 


M=SYMB.ASM 


ACBP=48 


0442:0008 


0002 


C=BSS 


S= BSS 


G=DGROUP 


M=QUAL.ASM 


ACBP=48 


0442:000A 


OOOE 


C=BSS 


S= BSS 


G=DGROUP 


M=BRK 


ACBP=48 



For each segment in each module, this map includes the address, length in 
bytes, class, segment name, group, module, and ACBP information. 
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If the same segment appears in more than one module, each module will 
appear as a separate line (for example, SYMB.ASM). Most of the infor- 
mation in the detailed segment map is self-explanatory, except for the 
ACBP field. 

The ACBP field encodes the A {alignment) and C (combining) attributes into a 
set of 4 bit fields, as defined by Intel. TLINK uses only two of the fields, the 
A and C fields. The ACBP value in the map is printed in hexadecimal: The 
following values of the fields must be OR'ed together to arrive at the ACBP 
value printed. 



Field 



Value Description 



The A field 00 An absolute segment 

(alignment) 20 A byte-ahgned segment 

40 A word-auened segment 

60 A paragrapn-aligned segment 

80 A page-ahgned segment 

AO An unnamed absolute portion of storage 

The C field 00 May not be combined 

(combination) 08 A public combining segment 



The /I Option 

The /I option creates a section in the .MAP file for source code line 
nun\bers. To use it, you must have created the .OBJ files by compiling with 
the -y (Line numbers... On) option. If you tell TLINK to create no map at aU 
(using the /x option), this option will have no effect. 



The /i Option 

The /i option causes trailing segments to be output into the executable file 
even if the segments do not contain data records. Note that this is not 
normally necessary. 



The /n Option 

The /n option causes the linker to ignore default libraries specified by some 
compilers. This option is necessary if the default libraries are in another 
directory, because TLINK does not support searching for libraries. You may 
want to use this option when linking modules written in another language. 
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The /c Option 

The /c option forces the case to be significant in publics and externals. For 
example, by default, TLINK regards fred, Fred, and FRED as equal; the /c 
option makes them different. 



The /d Option 

Normally, TLINK will not warn you if a symbol appears in more than one 
library file. If the symbol must be included in the program, TLINK will use 
the copy of that symbol in the first file mentioned on the command line. 
Since this is a commonly used feature, TLINK does not normally warn 
about the duplicate symbols. The following hypothetical situation 
illustrates how you might want to use this feature. 

Suppose you have two libraries: one called SUPPORT.LIB, and a supple- 
mental one called DEBUGSUP.LIB. Suppose also that DEBUGSUP.LIB 
contains duplicates of some of the routines in SUPPORT.LIB (but the 
duplicate routines in DEBUGSUP.LIB include slightly different 
functionality, such as debugging versions of the routines). If you include 
DEBUGSUP.LIB first in the link command, you will get the debugging 
routines and not the routines in SUPPORT.LIB. 

If you are not using this feature or are not sure which routines are 
duplicated, you may include the /d option. This will force TLINK to list all 
symbols duplicated in libraries, even if those symbols are not going to be 
used in the program. 

The /d option also forces TLINK to warn about symbols that appear both in 
an .OBJ and a .LIB file. In this case, since the symbol that appears in the first 
(left-most) file listed on the command line is the one linked in, the symbol 
in the .OBJ file is the one that will be used. 



The /e Option 

The library files that are shipped with Turbo C all contain an Extended 
Dictionary with information that enables TLINK to link faster with those 
libraries. This Extended Dictionary can also be added to any other library 
file using the /E option with TLIB (see the section on TLIB, beginning on 
page 220). 

Although linking with libraries that contain an Extended Dictionary is 
faster, there are two reasons you might want to use the /e switch, which 
disables the use of the Extended Dictionary: 
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■ A program may need slightly more memory to link when an Extended 
Dictionary is used. 

■ TLDSTK will ignore any debugging information contained in a library that 
has an Extended Dictionary, unless /e is used. 

The /t Option 

If you compiled your file in the tiny memory model and link it with this 
switch toggled on, TLDSfK will generate a .COM file instead of the usual 
.EXE file. 

When /t is used, the default extension for the executable file is .COM. 

Note: .COM files may not exceed 64K in size, may not have any segment- 
relative fixups, may not define a stack segment, and must have a starting 
address equal to 0:100h. When an extension other than .COM is used for 
the executable file (.BIN, for example), the starting address may be either 
0:0 or 0:100h. 



The /v Option 

The /v option directs TLINK to include debugging information in the 
executable file. 

Note: When linking with the /v option, TLINK initializes all segments. If 
you have a program that runs differently when linked with debug 
information, you have an uninitialized variable somewhere. 



The /3 Option 

The /3 option should be used when one or more of the object modules 
linked has been produced by TASM or a compatible asembler, and contains 
32-bit code for the 80386 processor. This option increases the memory 
requirements of TLINK and slows down linking, so it should be used only 
when necessary. 



Restrictions 

As we said earlier, TLINK is lean and mean; it does not have an excessive 
supply of options. Following are the only serious restrictions to TLINK: 

■ Overlays are not supported. 
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D Common variables are only partly supported: A public must be supplied 
to resolve them. 

B You can have a maximum of about 4,000 logical segments. 

□ Segments that are of the same name and class should either all be able to 
be combined, or not. 

D TLINK loads last any segments of class STACK, even if they are part of 
DGROUP. 

D Code compiled in Microsoft C or Microsoft Fortran cannot be linked with 
TLINK. This is because Microsoft languages have undocumented object 
record formats in their .OBJ files, which TLINK does not currently 
support. 

TLINK is designed to be used with Turbo Assembler, Turbo C (both the 
integrated environment and command-Une versions). Turbo Prolog, and 
other compilers; however, it is not a general replacement for MS Link. 



Error Messages 

TLINK has three types of errors: fatal errors, nonfatal errors, and warnings. 

D A fatal error causes TLINK to stop immediately; the .EXE and .MAP files 
are deleted. 

Q A nonfatal error does not delete .EXE or .MAP files, but you shouldn't 
try to execute the .EXE file. 

B Warnings are just that: warnings of conditions that you probably want to 
fix. When warnings occur .EXE and .MAP files are still created. 

The following generic names and values appear in the error messages listed 
in this section. When you get an error message, the appropriate name or 
value is substituted. 

<sname> symbol name 

<raname> module name 

<fname> file name 

XXXXh a 4-digit hexadecimal number, followed by 'h' 



Fatal Errors 

When fatal errors happen, TLINK stops and deletes the .EXE and .MAP 
files. 
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XXXXXXXX.XXX: bad object file 

An ill-formed object file was encountered. This is most commonly caused 
by naming a source file or by naming an object file that was not completely 
built. This can occur if the machine was rebooted during a compile, or if a 
compiler did not delete its output object file when a Ctrl-Break was struck. 

XXXXXXXX.XXX: unable to open file 

This occurs if the named file does not exist or is misspelled. 

Bad character in parameters 

One of the following characters was encountered in the command line or 
in a response file: 

"*< = >?[]! 

or any control character other than horizontal tab, linefeed, carriage return, 
or Ctrl-Z. 

msdos error, ax = XXXXh 

This occurs if an MS-DOS call returned an unexpected error. The AX value 
printed is the resulting error code. This could indicate a TLINK internal 
error or an MS-DOS error. The only MS-DOS calls TLINK makes where this 
error could occur are read, write, and close. 

Not enough memory 

There was not enough memory to complete the Unk process. Try removing 
any terminate-and-stay-resident applications currently loaded or reduce 
the size of any RAM disk currently active. Then run TLINK again. 

Segment exceeds 64K 

This message will occur if too much data was defined for a given data or 
code segment, when segments of the same name in different source files are 
combined. This message also occurs if a group exceeds 64K bytes when the 
segments of the group are combined. 

Symbol limit exceeded 

You can define a maximum of 8,182 public symbols, segment names, and 

group names in a single link. This message is issued if that limit is 

exceeded. 

Unexpected group definition 

Group definitions in an object file must appear in a particular sequence. 
This message will generally occur only if a compiler produced a flawed 
object file. If this occurs in a file created by Turbo Assembler, try re- 
compiling the file. If the problem persists, contact Borland. 

Unexpected segment definition 

Segment definitions in an object file must appear in a particular sequence. 
This message will generally occur only if a compiler produced a flawed 
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object file. If this occurs in a file created by Turbo Assembler, try 
recompiling the file. If the problem persists, contact Borland. 

Unknown option 

A slash character (/) was encountered on the command line or in a 
response file without being followed by one of the allowed options. 

Write failed, disk full? 

This occurs if TLINK could not write all of the data it attempted to write. 
This is almost certainly caused by the disk being full. 

Nonfatal Errors 

TLINK has only two nonfatal errors. As mentioned, when a nonfatal error 
occurs, the .EXE and .MAP files are not deleted. Here are the error 
messages: 

XXX is unresolved in module YYY 

The named symbol is referenced in the given module but is not defined 
anywhere in the set of object files and libraries included in the link. Check 
the spelling of the symbol for correctness. 

Fixup overflow, frame = xxxxh, target = xxxxh, 
offset = xxxxh in module XXXXXXX 

This indicates an incorrect data or code reference in an object file that 
TLINK must fix up at link time. In a fixup, the object file indicates the name 
of a memory location being referenced and the name of a segment that the 
memory location should be in. The frame value is the segment where the 
memory location should be according to the object file. The target value is 
the segment where the memory location actually is. The offset field is the 
offset within the target segment where the memory location is. 

This message is most often caused by a mismatch of memory models. A 
near call to a function in a different code segment is the most likely cause. 
This error can also result if you generate a near call to a data variable or a 
data reference to a function. 

To diagnose the problem, generate a map with public symbols (/m). The 
value of the target and offset fields in the error message should be the 
address of the symbol being referenced. If the target and offset fields do not 
match some symbol in the map, look for the symbol nearest to the address 
given in the message. The reference is in the named module, so look in the 
source file of that module for the offending reference. 

If these techniques do not identify the cause of the failure, or if you are 
programming in assembly language or some other high-level language 
besides Turbo Assembler, there may be other possible causes for this 
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message. Even in Turbo Assembler, this message could be generated if you 
are using different segment or group names than the default values for a 
given memory model. 



Warnings 

TLINK has only three warnings. The first two deal with duplicate 
definitions of symbols; the third, applicable to tiny model programs, 
indicates that no stack has been defined. Here are the messages: 

Warning: XXX is duplicated in module YYY 

The named symbol is defined twice in the named module. This could 
happen in Turbo Assembler object files, for example, if two different pascal 
names were spelled using different cases in a source file. 

Warning: XXX defined in module YYY is duplicated in module ZZZ 

The named symbol is defined in each of the named modules. This could 
happen if a given object file is named twice in the command line, or if one 
of the two copies of the symbol were misspelled. 

Warning: no stack 

This warning is issued if no stack segment is defined in any of the object 
files or in any of the libraries included in the link. This is a normal message 
for the tiny memory model in Turbo C, or for any application program that 
will be converted to a .COM file. For other programs, this indicates an error. 

If a Turbo Assembler program produces this message for any but the tiny 
memory model, check the COx start-up object files to be sure they are 
correct. 



TLIB: The Turbo Librarian 

TLIB is Borland's Turbo Librarian: It is a utUity that manages libraries of 
individual .OBJ (object module) files. A library is a very convenient way of 
dealing with a collection of object modules as a single unit. 

Using TLIB, you can build your own libraries, or you can modify your own 
libraries, libraries furnished by other programmers, or commercial hbraries 
you have purchased. You can use TLIB to 

■ create a new library from a group of object modules 

■ add object modules or other hbraries to an existing library 

■ remove object modules from an existing library 

■ replace object modules from an existing Ubrary 
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Q extract object modules from an existing library 
ta list the contents of a new or existing library 

When modifying an existing library, TLIB always creates a copy of the 
original library with a .BAK extension. 

TLIB can also create (and include in the library file) an Extended 
Dictionary, which may be used to speed up linking. See the section on the 
/E option for details. 

Although TLIB is not essential to creating executable programs with Turbo 
Assembler, it is a useful programmer productivity tool. You will find TLIB 
indispensable for large development projects. If you work with object 
modiile libraries developed by others, you can use TLIB to maintain those 
libraries when necessary. 

The Advantages of Using Object Module Libraries 

When you program in Assembler, you often create a collection of useful 
Assembler functions, like the functions in the Assembler run-time library. 
Because of Assembler's modularity, you are likely to split those functions 
into many separately compiled source files. You use only a subset of 
functions from the entire collection in any particular program. It can 
become quite tedious, however, to figure out exactly which files you are 
using. If you always include all the source files, on the other hand, your 
program becomes extremely large and unwieldy. 

An object module library solves the problem of managing a collection of 
Assembler functions. When you link your program with a library, the 
linker scans the library and automatically selects only those modules 
needed for the current program. In addition, a library consumes less disk 
space than a collection of object module files, especially if each of the object 
files is small. A library also speeds up the action of the linker, because it 
only opens a single file, instead of one file for each object module. 

The Components of a TLIB Command Line 

To get a summary of TLIB's usage, just type TLIB at the DOS prompt. 

The TLIB command line takes the following general form, where items 
listed in square brackets {{like this]) are optional: 

tlib libname [/C] [/E] [operations] [, listfile] 
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This section summarizes each of these command-line components; the 
following sections provide details about using TLIB. For examples of how 
to use TLIB, refer to the "Examples" section on page 226. 

Component Description 

tlib The command name that invokes TLIB, 

libname The DOS path name of the library you want to create or manage. 

Every TLIB command must be given a libname. Wildcards are not 
allowed. TLIB assumes an extension of .LIB if none is given. We 
recommend that you do not use an extension other than .LIB, 
since TASM's object-make facility requires the .LIB extension in 
order to recognize library files. 

Note that if the named library does not exist and there are add 
operations, TLIB creates the library. 

/C The 'Case sensitive' flag. This option is not normally used; see 

"Advanced Operation: The /C Option " for a detailed 
explanation. 

/E Create Extended Dictionary; see "Creating an Extended 

Dictionary: The /E Option" on page 226 for a detailed 
explanation. 

operations The list of operations TLIB performs. Operations may appear in 
any order. If you orUy want to examine the contents of the library, 
you don't have to give any operations at all. 

listf ile The name of the file listing library contents. The listfile name (if 

given) must be preceded by a comma. If you do not give a file 
name, no listing is produced. The listing is an alphabetical list of 
each module, followed by an alphabetical list of each public 
symbol defined in that module. The default extension for the 
listfile is .LST. 

You may direct the listing to the screen by using the listfile name 
CON, or to the printer by using the name PRN. 



The Operation List 

The operation list describes what actions you want TLIB to do. It consists of 
a sequence of operations given one after the other. Each operation consists 
of a one- or two-character action symbol followed by a file or module name. 
Whitespace may be used around either the action symbol or the file or 
module name, but it cannot appear in the middle of a two-character action 
or in a name. 
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You can put as many operations as you like on the command line, up to the 
DOS-imposed line-length limit of 127 characters. The order of the opera- 
tions is not important. TLIB always applies the operations in a specific 
order: 

1. All extract operations are done first. 

2. All remove operations are done next. 

3. All add operations are done last. 

Replacing a module is treated as first removing it, then adding the 
replacement module. 

File and Module Names 

When TLIB adds an object module file to a Ubrary, the file is simply called a 
module. TLIB finds the name of a module by taking the given file name and 
stripping any drive, path, and extension information from it. (Typically, 
drive, path, and extension are not given.) 

Note that TLIB always assumes reasonable defaults. For example, to add a 
module that has an .OBJ extension from the current directory, you only 
need to supply the module name, not the path and .OBJ extension. 

Wildcards are never allowed in file or module names. 



TLIB Operations 

TLIB recognizes three action symbols (-, +, *), which you can use singly or 
combined in pairs for a total of five distinct operations. For operations that 
use a pair of characters, the order of the characters is not important. The 
action symbols and what they do are listed here: 
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Action 

Symbol Name 



Description 



+ Add TLIB adds the named file to the library. If the file has no 

extension given, TLIB assumes an extension of .OBJ. If 
the file is itself a library (with a .LIB extension), then the 
operation adds all of the modules in the named library to 
tlie target library. 

If a module being added already exists, TLIB displays a 
message and does not add the new module. 

- Remove TLIB removes the named module from the library. If the 

module does not exist in the library, TLIB displays a 
message. 

* Extract TLIB creates the named file by copying the corre- 

sponding module from the library to the file. If the 
module does not exist, TLIB displays a message and does 
not create a file. If the named file already exists, it is 
overwritten. 

-+ Replace TLIB replaces the named module with the corre- 

+- spending file. This is just shorthand for a remove 

followed by an add operation. 

-* Extract & TLIB copies the named module to the 

*- Remove corresponding file name and then removes it from the 

library. This is just a shorthand for an extract followed by 

a remove operation. 

A remove operation only needs a module name, but TLIB allows you to 
enter a full path name with drive and extension included. However, 
everything but the module name is ignored. 

It is not possible to rename modules in a library. To rename a module, you 
must first extract and remove it, rename the file just created, and, finally, 
add it back into the library. 



Creating a Library 



To create a library, you simply add modules to a library that does not yet 
exist. 
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Using Response Files 



When you are dealing with a large number of operations, or if you find 
yourself repeating certain sets of operations over and over, you will 
probably want to start using response files. A response file is simply an 
ASCII text file that contains all or part of a TLIB command. Using response 
files, you can build TLIB commands larger than would fit on one DOS 
command line. 

To use a response file pathname, specify @<pathname> at any position on the 
TLIB command line. 

D More than one line of text can make up a response file; you use the "and" 
character (&) at the end of a line to indicate that another line follows. 

B You don't need to put the entire TLIB command in the response file; the 
file can provide a portion of the TLIB command line, and you can type in 
the rest. 

■ You can use more than one response file in a single TLIB command line. 

See the "Examples" section on page 226 for a sample response file and a 
TLIB command line incorporating it. 



Advanced Operation: The IC Option 

When you add a module to a Ubrary, TLIB maintains a dictionary of all 
public symbols defined in the modules of the library. All symbols in the 
library must be distinct. If you try to add a module to the library that 
would cause a dupUcate symbol, TLIB will display a message and not add 
the module. 

Normally, when TLIB checks for duplicate symbols in the library, 
uppercase and lowercase letters are not considered as distinct. For example, 
the sjnnbols lookup and LOOKUP are treated as duplicates. Since Assembler 
does treat uppercase and lowercase letters as distinct, you need to use the /C 
option to add a module to a library that includes a symbol that differs only 
in case from one already in the library. The /C option forces TLIB to accept a 
module with sjnnbols in it that differ only in case from symbols already in 
the library. 

It may seem odd that without the /C option TLIB rejects symbols that differ 
only in case, especially since Assembler is a case-sensitive language. The 
reason is that some linkers fail to distinguish between symbols in a library 
that differ only in case. 
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TLINK has no problem distinguishing uppercase and lowercase symbols, 
and it will properly accept a library containing symbols that differ only in 
case. As long as you only use the library with TLUSJK, you can use the TLIB 
/C option without any problems. 

However, if you want to use the library with other linkers (or allow other 
people to use the library with other linkers), for your own protection you 
should not use the /C option. 

Examples 

Here are some simple examples demonstrating the different things you can 
do with TLIB. 

1. To create a library named MYLIB.LIB with modules X.OBJ, Y.OBJ, and 
Z.OBJ, type 

tlib mylib +x +y +z 

2. To create a library as in #1 and get a listing, too, type 

tlib mylib +x +y +z, mylib. 1st 

3. To get a listing of an existing library CS.LIB, type 

tlib cs, cs.lst 

4. To replace module X.OBJ with a new copy, add A.OBJ and delete Z.OBJ 
from MYLIB.LIB, type 

tlib mylib -+x +a -z 

5. To extract module Y.OBJ from MYLIB.LIB and get a listing, type 

tlib mylib *y, mylib. 1st 

6. To create a new library with modules A. OBJ, B.OBJ, ..., G.OBJ using a 
response file: 

First create a text file, ALPHA.RSP, with 

+a.obj +b.obj +c.obj & 
+d.obj +e.obj +f.obj & 
+g.obj 

Then use the TLIB command 

tlib alpha Salpha.rsp, alpha. 1st 

Creating an Extended Dictionary: The IE Option 

To speed up linking with large library files, you can direct TLIB to create an 
Extended Dictionary and append it to the library file. This dictionary 
contains, in a very compact form, information that is not included in the 



226 Turbo Assembler Reference Guide 



standard library dictionary. This information enables TLINK to process 
library files faster, especially when they are located on a floppy disk or a 
slow hard disk. All the libraries on the Turbo Assembler distribution disks 
contain the Extended Dictionary. 

To create an Extended Dictionary for a library that is being modified, just 
use the /E option when you invoke TLIB to add, remove, or replace 
modules in the library. To create an Extended Dictionary for an existing 
library that you don't want to modify, use the /E option and ask TLIB to 
remove a nonexistent module from the library. TLIB will display a warning 
that the specified module was not found in the library, but it will also create 
an Extended Dictionary for the specified library. For example, enter 

tlib /E mylib -bogus 

GREP: A File-Search Utility 

GREP is a powerful search utility that can search for text in several files at 
once. 

The general command-line syntax for GREP follows: 

grep [options] searchstring filespec [filespec filespec ... filespec] 

For example, if you want to see in which source files you call the 
setupmodem function, you could use GREP to search the contents of all the 
.ASM files in your directory to look for the string setupmodem, like this: 

grep setupmodem *.asm 

The GREP Options 

In the command line, options are one or more single characters preceded by 
a hyphen symbol (-). Each individual character is a switch that you can turn 
on or off: type the plus (+) after a character to turn the option on, or type a 
hyphen (-) after the character to turn the option off. 

The default is on (the + is implied): for example, -r means the same thing as 
-r+. You can list multiple options individually (like this: -i -d -1), or you 
can combine them (like this: -ild or -11 -d, and so forth); they're all the 
same to GREP. 

Here is a list of the option characters used with GREP and their meanings: 

-c Count only: Only a count of matching lines is printed. For each file 
that contains at least one matching line, GREP prints the file name 
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and a count of the number of matching lines. Matching lines are 
not printed. 

-d Directories: For each filespec specified on the command line, GREP 
searches for all files that match the file specification, both in the 
directory specified and in all subdirectories below the specified 
directory. If you give a filespec without a path, GREP assumes the 
files are in the current directory. 

-i Ignore case: GREP ignores uppercase/lowercase differences (case- 
folding). GREP treats all letters a-z as being identical to the 
corresponding letters A-Z in all situations. 

-1 List match files: Only the name of each file containing a match is 
printed. After GREP finds a match, it prints the file name and 
processing immediately moves on to the next file. 

-n Numbers: Each matching line that GREP prints is preceded by its 
line number. 

-o UNIX output format: Changes the output format of matching lines 
to support more easily the UNIX style of command-line piping. All 
lines of output are preceded by the name of the file that contained 
the matching line. 

-r Regular expression search: The text defined by searchstring is 
treated as a regular expression instead of as a literal string. 

-u Update options: GREP will combine the options given on the 
command line with its default options and write these to the 
GREP.COM file as the new defaults. (In other words, GREP is self- 
configuring.) This option allows you to tailor the default option 
settings to your own taste. 

-V Non-match: Only non-matching lines are printed. Only lines that do 
not contain the search string are considered to be non-matching 
lines. 

-w Word search: Text found that matches the regular expression will 
be considered a match only if the character immediately preceding 
and following cannot be part of a word. The default word character 
set includes A-Z, 9-0, and the underscore (_). An alternate form of 
this option allows you to specify the set of legal word characters. Its 
form is -w[set], where set is any valid regular expression set 
definition. If alphabetic characters are used to define the set, the set 
will automatically be defined to contain both the uppercase and 
lowercase values for each letter in the set, regardless of how it is 
typed, even if the search is case-sensitive. If the -w option is used 
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in combination with the -u option, the new set of legal characters is 
saved as the default set. 

-z Verbose: GREP prints the file name of every file searched. Each 
matching line is preceded by its line number. A count of matching 
lines in each file is given, even if the count is zero. 



Order of Precedence 

Remember that each of GREP's options is a switch: Its state reflects the way 
you last ''flipped" it. At any given time, each option can only be on or off. 
Each occurrence of a given option on the command line overrides its 
previous definition. For example, 

grep -r -i — d -i -r- main( my*. asm 

Given this command line, GREP will run with the -d option on, the -i 
option on, and the -r option off. 

You can install your preferred default setting for each option in GREP.COM 
with the -u option. For example, if you want GREP to always do a verbose 
search (-z on), you can install it with the following command: 

grep -u -z 



The Search String 



The value of searchstring defines the pattern GREP will search for. A search 
string can be either a regular expression or a literal string. In a regular 
expression, certain characters have special meanings: They are operators 
that govern the search. In a literal string, there are no operators; each 
character is treated literally. 

You can enclose the search string in quotation marks to prevent spaces and 
tabs from being treated as delimiters. Matches will not cross line 
boundaries (a match must be contained in a single line). 

An expression is either a single character or a set of characters enclosed in 
brackets. A concatenation of regular expressions is a regular expression. 



Operators in Regular Expressions 

When you use the -r option, the search string is treated as a regular 
expression (not a literal expression) and the following characters take on 
special meanings: 
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^ A circumflex at the start of the expression matches the start of a 
line. 

$ A dollar sign at the end of the expression matches the end of a line. 

A period matches any character. 

* An expression followed by an asterisk wildcard matches zero or 
more occurrences of that expression. For example, in fo*, the * 
operates on the expression o; it matches /, fo, foo, and so on, (/ 
followed by zero or more os), but doesn't match fa. 

+ An expression followed by a plus sign matches one or more 
occurrences of that expression: fo+ matches fo, foo, and so on, but 
not/. 

I ] A string enclosed in brackets matches any character in that string, 
but no others. If the first character in the string is a circumflex {^), 
the expression matches any character excqjt the characters in the 
string. For example, [xyz] matches x, y, or z, while \^xyz) matches a 
and h, but not x, y, or z. You can specify a range of characters with 
two characters separated by a hyphen (-). These can be combined to 
form expressions (like [a-bd-z?] to match ? and any lowercase letter 
except c). 

\ The backslash escape character tells GREP to seach for the literal 
character that follows it. For example, \. matches a period instead 
of ''any character." 

Note: Four of the previously described characters ($, ., *, and +) do not have 
any special meaning when used within a bracketed set. In addition, the 
character ^ is only treated specially if it immediately follows the beginning 
of the set definition (that is, immediately after the [). 

Any ordinary character not mentioned in the preceding list matches that 
character. (> matches >, # matches #, and so on.) 



The File Specification 

The third item in the GREP command line is filespec, the file specification; it 
tells GREP which files (or groups of files) to search, filespec can be an 
explicit file name, or a generic file name incorporating the DOS ? and * 
wildcards. In addition, you can enter a path (drive and directory infor- 
mation) as part of filespec. If you give filespec without a path, GREP only 
searches the current directory. 
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Examples with Notes 



The following examples assume that all of GREP's options default to off: 
Example 1 

Command line: grep start: *.asm 



Matches: 


start: 




restart: 


Does not match: 


restarted: 




ClockStart: 



Files Searched: *.ASM in current directory. 

Note: By default, the search is case-sensitive. 



Example 2 

Command line: 
Matches: 

Does not match: 

Files Searched: 
Note: 



Example 3 

Command line: 
Matches: 



grep -r [^a-z]main\ *( *.asm 

main {i: integer) 
main (i,j: integer) 
if (main ()) halt; 

mymainO 
MAIN(i: integer); 

*.ASM in current directory. 

GREP searches for the word main with no preceding 
lowercase letters (['^a-z]), followed by zero or more 
occurrences of blank spaces (\ *), then a left 
parenthesis. 

Since spaces and tabs are normally considered to be 
command-line delimiters, you must quote them if you 
want to include them as part of a regular expression. 
In this case, the space after main is quoted with the 
backslash escape character. You could also accomplish 
this by placing the space in double quotes 

[^a-z]main" "* 



grep -ri [a-c] :\\data\.fil *.asm *.inc 

A:\data.fil 
c:\Data.Fil 
B:\DATA.FIL 
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Does not match: 

Files Searched: 
Note: 



Example 4 

Command line: 
Matches: 



Does not match: 

Files Searched: 
Note: 

Example 5 

Command line: 
Matches: 



Does not match: 

Files searched: 
Note: 
Example 6 

Command line: 

Matches: 
Does not match: 



d:\data.fil 
a:data.fil 

*.ASM and *.INC in current directory. 

Because the backslash and period characters (\ and .) 
usually have special meaning, if you want to search 
for them, you must quote them by placing the 
backslash-escape character immediately in front of 
them. 



grep -ri ["a-zlwordCa-z] *.doc 

every new word must be on a new line. 

MY WORD! 

word — smallest unit of speech. 

In the beginning there was the WORD, and the WORD 

Each file has at least 2000 words. 
He misspells toward as toword. 

*.DCXZ! in the current directory. 

This format basically defines how to search for a 
given word. 



grep -iw word *.doc 

every new word must be on a new line However, 

MY WORD! 

word: smallest unit of speech which conveys meaning. 

In the beginning there was the WORD, and the WORD 

each document contains at least 2000 words! 

He seems to continually misspell "toward" as "toword. 

*.doc in the current directory. 

This format defines a basic "word" search. 



grep "search string with spaces" *.doc *.asm 
a:\work\myfile.* 

This is a search string with spaces in it. 

THIS IS A SEARCH STRING WITH SPACES IN IT. 
This is a search string with many spaces in it. 
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Files Searched: 

Note: 

Example 7 

Command line: 
Matches: 



Does not match: 
Files Searched: 
Note: 



Example 8 

Command line: 

Matches: 
Does not match: 
Files Searched: 
Note: 



*.DOC and *.ASM in the current directory, and 
MYFILE.* in a directory called \ WORK on drive A:. 

This is an example of how to search for a string with 
embedded spaces. 



grep -rd "[ ,.:?'\"]"$ \*.doc 

He said hi to me. 

Where are you going? 

Happening in anticipation of a unique situation, 

Examples include the following: 

"Many men smoke, but fu man chu." 

He said "Hi" to me 

Where are you going? I'm headed to the beach this 

*.DC)C in the root directory and all its subdirectories 
on the current drive. 

This example searches for the characters , .:?' and " 
at the end of a line. Notice that the double quote 
within the range is preceded by an escape character 
so it is treated as a normal character instead of as the 
ending quote for the string. Also, notice how the $ 
character appears outside of the quoted string. This 
demonstrates how regular expressions can be con- 
catenated to form a longer expression. 



grep -ild " the " \*.doc 

or grep -i -1 -d " the " \*,doc 

or grep -il -d " the " \*.doc 

Anyway, this is the time we have 
do you think? The main reason we are 

He said "Hi" to me just when I 

Where are you going? I'll bet you're headed to 

*.DOC in the root directory and all its subdirectories 
on the current drive. 

This example ignores case and just prints the names 
of any files that contain at least one match. The three 
examples show different ways of specifying multiple 
options. 
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OBJXREF: The Object Module Cross- 
Ref erence Utility 

OBJXREF is a utility that examines a list of object files and library files and 
produces reports on their contents. One type of report lists definitions of 
public names and references to them. The other type lists the segment sizes 
defined by object modules. 

There are two categories of public names: global variables and function 
names. The TESTl.ASM and TEST2.ASM files in the section "Sample 
OBJXREF Reports" on page 238 illustrate definitions of public names and 
external references to them. 

Object modules are object (.OBJ) files produced by TC, TCC, or TASM. A 
library (.LIB) file contains multiple object modules. An object module 
generated by TASM is given the same name as the .ASM source file it was 
compUed from, unless a different output file name is specifically indicated 
on the command line. 



The OBJXREF Command Line 

The OBJXREF command line consists of the word OBJXREF, followed by a 
series of command-line options and a list of object and library file names, 
separated by a space or tab character. The syntax is as follows: 

OBJXREF < options > filename < filename . . . > 

The command-line options determine the kind of reports OBJXREF will 
generate and the amount of detail that OBJXREF will provide. They are 
discussed in more detail in the next section "Command-Line Options." 

Each option begins with a forward slash (/) followed by a one- or two- 
character option name. 

Object files and library files may be specified either on the command line or 
in a response file. On the command line, file names are separated by a space 
or a tab. All object modules specified as .OBJ files are included in reports. 
Like TLINK, however, OBJXREF includes only those modules from .LIB 
files which contain a public name referenced by an .OBJ file or by a 
previously included module from a .LIB file. 

As a general rule, you should list all the .OBJ and .LIB files that are needed 
if the program is to link correctly, including the libraries. 

File names may include a drive and directory path. The DOS ? and * 
wildcard characters may be used to identify more than one file. File names 
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may refer to .OBJ object files or to .LIB library files. (If no file extension is 
given, the .OBJ extension is assumed.) 

Options and file names may occur in any order in the connmand line. 

OBJXREF reports are written to the DOS standard output. The default is the 
screen. The reports may be sent to a printer (as with >LPT1 :) or to a file (as 
with >lstfile) with the DOS redirection character (>). 

Entering OBJXREF with no file names or options produces a summary of 
available options. 



Command-Line Options 

OBJXREF command-line options fall into two categories: control options 
and report options. 

Control Options 

Control options modify the default behavior of OBJXREF (the default is 
that none of these options are enabled). 

/I Ignore case differences in public names: Use this option if you use 
TLINK without the /c option (which makes case differences 
significant). 

/F Include Full library: All object modules in specified .LIB files are 
included even if no public names they contain are referenced by an 
object module being processed by OBJXREF. This provides 
information on the entire contents of a library file. (See example 4 in 
the section "OBJXREF Examples.") 

/V Verbose output: Lists names of files read and displays totals of public 
names, modules, segments, and classes. 

/Z Include Zero Length Segment Definitions: Object modtiles may define 
a segment without allocating any space in it. Listing these zero length 
segment definitions norn\ally makes the module size reports harder to 
use but it can be valuable if you are trying to remove all definitions of 
a segment. 

Report Options 

Report options govern what sort of report is generated, and the amoimt of 
detail OBJXREF provides. 
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/RC Report by Class Type: Module sizes ordered by class type of 
segment. 

/RM Report by Module: Public names ordered by defining module. 

/RP Report by Public Names: Public names in order with defining 
module name. 

/RR Report by Reference: Public name definitions and references 
ordered by name. (This is the default if no report option is 
specified.) 

/RS Report of Module Sizes: Module sizes ordered by segment name. 

/RU Report of Unreferenced Symbol Names: Unreferenced public 
names ordered by defining module. 

/RV Verbose Reporting: OBJXREF produces a report of every type. 

/RX Report by External Reference: External references ordered by 
referencing module name. 

Response Files 

The command line is limited by DOS to a maximum of 128 characters. If 
your list of options and file names will exceed this limit, you must place 
your file names in a response file. 

A response file is a text file that you make with an text editor. Since you 
may already have prepared a list of the files that make up your program for 
other Turbo Assembler programs, OBJXREF recognizes several response 
file types. 

Response fUes are called from the command line using one of the following 
options. The response file name must follow the option without an 
intervening space (/Lresp not /L resp). 

More than one response file can be specified on the command line, and 
additional .OBJ and .LIB file names may precede or follow them. 



Freeform Response Files 

You can create a freeform response file with a text editor. Just list the names 
of all .OBJ and .LIB files needed to make your .EXE file. 

To use freeform files with OBJXREF, type in each file name on the 
command line, preceded by a at-sign (@), and separate it from other 
command-line entries with a space or tab: 
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Sfilename @filename 



Note: Any file name that is listed in the response file without an extension 
is assumed to be a .OBJ file. 



Linker Response Files 

Files in TLINK response file format can also be used by OBJXREF. A linker 
response file caUed fi*om the command line is preceded by /L: 

/Lfilename 

To see how to use one of these files, refer to Example 2 in the section, 
"Examples Using OBJXREF/' on page 243. 



The /D Command 

If you want OBJXREF to look for .OBJ files in a directory other than the 
current one, include the directory name on the command line, prefixed 
with /D: 

C:>OBJXREF/Ddirl [ ;dir2 [ ;dir3] ] 

or 

C:>OBJXREF/Ddirl [/Ddir2] [/Ddir3] 

OBJXREF will search each of the directories in the specified order for all 
object and library files. If you don't use the /D option, only the current 
directory will be searched. However, if you use a /D option, the current 
directory will not be searched unless it is included in the directory list. For 
example, to first search the BORLAND directory for files and then search 
the current directory, you would type 

C:>OBJXREF/Dborland; 

If multiple search directories are specified, and a file matching the file 
specification is found, OBJXREF will include the file as part of the cross- 
reference. OBJXREF will only continue to search the other directories for 
the same file specification if the file specification contains wildcards. 



The /O Command 

The /O option allows you to specify an output file where OBJXREF will 
send any reports generated. It has the following syntax: 
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C:>OBJXREF myfile.obj /RU /Ofilename.ext 

By default, all output is sent to the console. 

The /N Command 

You can limit the modules, segments, classes, or public names that 
OBJXREF reports on by entering the appropriate name on the command 
line, prefixed with the /N command. For example, 

OBJXREF <filelist> /RM /NTest 

tells OBJXREF to generate a report listing information only for the module 
named Test. 

Sample OBJXREF Reports 

Suppose you have two source files in your Turbo Assembler directory, and 
wish to generate OBJXREF reports on the object fQes compiled from them. 
The source files are called TESTl.ASM and 'ITEST2.ASM, and they look like 
this: 



; TESTl 


.ASM 








.MODEL 


small 






STACK 


200h 






EXTRN 


GOODBYE: BYTE 


/•refers to Goodbye 




EXTRN 


SAYHELLOrNEAR 


/refers to Say Hello 




PUBLIC 


HELLO 


/makes Hello public 




PUBLIC 


NOTUSED 


/makes NotUsed public 


.DATA 








HELLO 


DB 


'Hello', 10, 13, '$' 


/defines Hello 


NOTUSED 


DW 


9 




HIDDEN 


DW 


7 




.CODE 








SAYBYE 


PROC 


NEAR 


/defines SayBye 




mov 


dx, OFFSET GOODBYE 






mov 


ah, 9 






int 


21h 






ret 






SAYBYE 


ENDP 






START 


PROC 


NEAR 


/defines Start 




mov 


ax,8data 






mov 


ds,ax 






call 


SAYHELLO 


/refers to SayHello 
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call 


SAYBYE 




/refers to SayBye 


EXIT: 








mov 


ax,04C00h 






int 


21h 






START ENDP 








END START 








; TEST2.ASM 








.MODEL 


small 






EXTRN 


HELLO: BYTE 




; refers to Hello 


PUBLIC 


GOODBYE 




/•makes Goodbye public 


PUBLIC 


SAYHELLO 




;makes SayHello public 


.DATA 








GOODBYE DB 


'Goodbye', 10, 


13, '$ 


' ; defines Goodbye 


.CODE 








SAYHELLO 


PROC NEAR 




/defines SayHello 


mov 


dx, OFFSET HELLO 


/refers to Hello 


mov 


ah, 9 






int 


21h 






ret 








SAYHELLO 


ENDP 






END 









The object modules compiled from them are TESTl.OBJ and TEST2.0BJ. 
You can tell OBJXREF what kind of report to generate about these .OBJ files 
by entering the file names on the command line, followed by a /R and a 
second letter denoting report type. 

Note: The examples that foUow show only fragments of the output. 



Report by Public Names (/RP) 

A report by public names lists each of the public names defined in the 
object modules being reported on, followed by the name of the module in 
which it is defined. 

If you enter the following on the command line, 

OBJXREF /RP testl test2 

OBJXREF will generate a report that looks like this: 
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Symbol Defined in 



GOODBYE 


TEST2 


HELLO 


TESTl 


NOTUSED 


TESTl 


SAYHELLO 


TEST2 



Report by Module (/RM) 

A report by module lists each object module being reported on, followed by 
a list of the public names defined in it. 

If you enter the following on the command line, 

OBJXREF /RM testl test2 

OBJXREF will generate a report that looks like this: 

Module: TESTl defines the following symbols: 

HELLO 
NOTUSED 

Module: TEST2 defines the following symbols: 

GOODBYE 
SAYHELLO 



Report by Reference (/RR) (Default) 

A report by reference lists each public name with the defining module in 
parentheses on the same line. Modules that refer to this public name are 
listed on following lines indented from the left margin. 

If you enter the following on the command line, 

OBJXREF /RR testl test2 

OBJXREF will generate a report that looks like this: 

GOODBYE (TEST2) 

TESTl 
HELLO (TESTl) 

TEST2 
NOTUSED (TESTl) 
SAYHELLO (TEST2) 

TESTl 



240 Turbo Assembler Reference Guide 



Report by External References (/RX) 

A report by external references lists each module followed by a list of 
external references it contains. 

If you enter the following on the command line, 

OBJXREF /RX testl test2 CS.LIB 

OBJXREF will generate a report that looks like this: 

Module: TESTl references the following symbols: 

GOODBYE 
SAYHELLO 

Module: TEST2 references the following: 

HELLO 

Report of Module Sizes (/RS) 

A report by sizes lists segment names followed by a list of modules that 
define the segment. Sizes in bytes are given in decimal and hexadecimal 
notation. The word uninitialized appears where no initial values are 
assigned to any of the symbols defined in the segment. Segments defined at 
absolute addresses in a .ASM file are flagged Abs to the left of the segment 
size. 

If you enter the following on the command line, 

OBJXREF /RS testl test2 

OBJXREF will generate a report that looks like this: 



/Module 


sizes by segment 






STACK 












512 


(00200h) 


TESTl, 


uninitialized 




512 


{00200h) 


total 




_DATA 












12 


(OOOOCh) 


TESTl 






10 


(OOOOAh) 


TEST2 






22 


(00016h) 


total 




_TEXT 












24 


(00018h) 


TESTl 






8 


(OOOOBh) 


TEST2 






32 


(00020h) 


total 
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Report by Class Type (/RC) 

A report by class type lists segment size definitions by segment class. The 
CODE class contains instructions, DATA class contains initialized data and 
BSS class contains unitialized data. Segments that don't have a class type 
will be listed under the notation "No class type." 

If you enter the following on the command line, 

OBJXREF /RC testl test2 

OBJXREF wiU generate a report that looks like this: 



; Module 


sizes by class 




CODE 








24 (OOOlSh) 


TESTl 




8 (OOOOSh) 


TEST2 




32 (00020h) 


total 


DATA 








12 (OOOOCh) 


TESTl 




10 (OOOOAh) 


TEST2 




22 (00016h) 


total 


STACK 








512 (00200h) 


TESTl, uninitialized 




512 (00200h) 


total 



Report of Unreferenced Symbol Names (/RU) 

A report of unreferenced symbol names lists modules that define public 
names not referenced in other modules. Such a symbol is either 

■ Referenced only from within the defining module and doesn't need to be 
defined as a public symbol (in that case, if the module is in C, the key- 
word static should be added to the definition; if the module is in TASM, 
just remove the public definition). 

■ Never used (therefore, it can be deleted to save code or data space). 
If you enter the following on the command line, 

OBJXREF /RU testl test2 

OBJXREF will generate a report that looks like this: 

Module: 

TESTl defines the following unreferenced symbols: 
NOTUSED 
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Verbose Reporting (/RV) 

If you enter /RV on the command line, one report of each type will be 
generated. 

Examples Using OBJXREF 

These examples assume that the application files are in the current 
directory of the default drive and that library files are in the \LIB directory. 

Example 1 OOBJXREF testl test2 \lib\io.lib 

In addition to the TESTl.OBJ and TEST2.0BJ files, the 
library file \LIB\IO.LIB is specified. Since no report type 
is specified, the resulting report is the default report by 
reference, listing public names and the modules that 
reference them. 

Example! OOBJXREF /RV /Ltestl.arf 

The TLINK response file TESTl.ARF contains the same 
list of files as the command line in Example 1. The /RV 
option is specified so that a report of every type will be 
generated. TESTl.ARF contains 

testl test2 
testl.exe 
testl. map 
\lib\io 

Examples oobjxref /f /rv \iib\io.iib 

This example reports on all the modules in the library 
file lO.LIB; OBJXREF can produce useful reports even 
when the files specified don't make a complete program. 
The /F causes all modules in lO.LIB file to be included in 
the report. 



OBJXREF Error Messages and Warnings 

OBJXREF generates two sorts of diagnostic messages: error messages and 
warnings. 
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Error Messages 

Out of memory 

OBJXREF performs its cross-referencing in RAM memory and may run out 
of memory even if TLINK is able to link the same list of files successfully. 
When this happens, OBJXREF aborts. Remove memory-resident programs 
to get more space or add more RAM. 



Warnings 

WARNING: Unable to open input file rrrr 

The input file rrrr could not be located or opened. OBJXREF proceeds to the 
next file. 

WARNING: Unknown option - oooo 

The option name oooo is not recognized by OBJXREF. OBJXREF ignores the 
option. 

WARNING: Unresolved symbol nnnn in module mmmm 

The public name nnnn referenced in module mmmm is not defined in any of 
the .OBJ or .LIB files specified. OBJXREF flags the symbol in any reports it 
generates as being referenced but not defined. 

WARNING: Invalid file specification ffff 

Some part of the file name ffff is invalid. OBJXREF proceeds to the next file. 

WARNING: No files matching ffff 

The file named ffff listed on the command line or in a response file could 
not be located or opened. OBJXREF skips to the next file. 

WARNING: Symbol nnnn defined in mmmml duplicated in mmmmZ 

Public name nnnn is defined in modules mmmml and mmmml. OBJXREF 
ignores the second definition. 

TCREF: The Source Module Cross-Reference 
Utility 

TCREF is designed to produce two reports: a cross-reference list of where 
all global symbols are used and defined, and a list of individual modules 
and the symbols used within them. 

TCREF accepts as input a group of .XRF files produced by TASM. These 
files contain cross-reference information for individual modules. From 



244 Turbo Assembler Reference Guide 



these input fQes, a single .REF file is produced that contains one or more 
reports in ASCII text. The command format follows: 

TCREF <XRF files separated by '+' characters> ',' 
<REF filename> <switches> 

For example, the following would take the FOOl.XRF, FC)02.XRF, and 
F003.XRF as input files and produce FOO.REF: 

TCREF fool+foo2+foo3,foo 



Response Files 



TCREF also accepts ASCII files as command strings. Simply precede the file 
name with an @ sign to include a file in the command string. For example, 

TCREF edofoo 

where DOFOO contains 

fool+foo2+foo3, foo 

will do the same thing as the previous example. 



Compatibility with TLINK 



TCREF accepts command strings that TLINK accepts. TCREF ignores any 
irrelevant switches and fields, such as any libraries or MAP files, or 
switches that pertain only to the linker function. Similarly, if an .XRF file 
cannot be located, TCREF will simply ignore it. 

Beware! When using a TLESJK response file, don't explicitly specify file 
extensions, since doing so will override TCREF's internal defaults and 
possibly result in disaster. For example, if the response file reads a 

fool+foo2+foo3,foo.exe 

you should not use this file without modification with TCREF because the 
.REF file it creates will be named FOO.EXE, presumably overwriting your 
program. 



Switches 

TCREF accepts all the switches present in TLINK, but most of them are 
discarded. TCREF only uses these switches: 

■ /c makes GLOBAL report case-sensitive. 
Appendix D. Turbo Assembler Utilities 245 



■ /r generates LOCAL reports for all the specified modules. 

■ /p# sets report page length to # lines. 

■ /w# sets report page width to # coliunns. 

Output 

TCREF takes great care to make semantic sense of symbols. Cross-reference 
information is useless when symbols with the same name but different 
meanings are lumped together. TCREF therefore takes into account the 
SCOPE of a symbol when producing its reports. Cross-reference infor- 
mation is always listed for the source file and source line number. 

The Global (or Linker-Scope) Report 

TCREF's global report lists cross-reference information for global symbols 
as they appear to the linker. Use the /c switch if you want to produce case- 
sensitive reports. 

In this report, global symbols appear alphabetically in the left column. 
References, organized by source file, are listed in the right column. 
Wherever #'s appear indicates that definition occurs at that line. 

Here's an example symbol printout: 

Global Symbols Cref } = definition 

BAR TEST.ASM: 1 3 6 9 12 15 18 + 

21 23 29 

* TEST2.ASM: 2 4 6 *8 

What does this tell you? The leading # sign before the TEST2.ASM 
indicates that BAR was defined somewhere in that module. For each source 
file, the source line at which the reference occurred is listed. This list can 
occupy more than one line, as in the case of the lines for TEST.ASM. The + 
character indicates that wrap has occurred. Finally, the # sign before the 8 
indicates that a definition of BAR occurred in TEST2. ASM on line 8. 



The Local (or Module-Scope) Report 

If you specify /r on the command line, a local report will be made for each 
module. It will contain all the symbols used in that module, listed in 
alphabetical order. The /c switch will have no effect on these reports, since 
the appropriate case-sensitivity has already been determined at assembly 
time. 
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Like global reports, references are organized by source file in the right 
column. A sample printout looks like this: 



Module TEST, ASM Symbols Cref i = definition 

UGH TEST. ASM: 1 3 6 9 12 15 18 

21 23 29 

* UGH. INC: *2 
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Error Messages 



This chapter describes all the messages that Turbo Assembler generates. 
Messages usually appear on the screen, but you can redirect them to a file 
or printer using the standard DOS redirection mechanism of putting the 
device or file name on the command line, preceded by the greater than (>) 
symbol. For example, 

TASM MYFILE >ERRORS 

Turbo Assembler generates several types of messages: 

El information messages 

■ warning messages 

■ error messages 

H fatal error messages 



Information Messages 



Turbo Assembler displays two information messages, one when it starts 
assembling your source file(s) and another when it has finished assembling 
each file. Here's a sample startup display: 

Turbo Assembler Version 1.00 Copyright (C)' 1988 Borland International 
Assembling file: TEST. ASM 

When Turbo Assembler finishes assembling your source file, it displays a 
message that summarizes the assembly process; the message looks like this: 
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Error messages; None 
Warning messages: None 
Remaining memory: 279k 

You can suppress all information messages by using the /T command-line 
option. This only suppresses the information messages if no errors occur 
during assembly. If there are any errors, the /T option has no effect and the 
normal startup and ending messages appear. 



Warning and Error Messages 

Warning messages let you know that something undesirable may have 
happened while assembling a source statement. This may be something 
such as the Turbo Assembler making an assumption that is usually valid, 
but may not always be correct. You should always examine the cause of 
warning messages to see if the generated code is what you wanted. 
Warning messages won't stop Turbo Assembler from generating an object 
file. These messages are displayed using the following format; 

**Warning** filename (line) message 

If the warning occurs while expanding a macro or repeat block, the 
warning message contains additional information, naming the macro and 
the line v^thin it where the warning occurred: 

**Warning** filename (line) macroname(macroline) message 

Error messages, on the other hand, will prohibit Turbo Assembler from 
generating an object file, but assembly wiU continue to the end of the file. 
Here's a t5^ical error message format; 

**Error** filename (line) message 

If the error occurs while expanding a macro or repeat block, the error 
message contains additional information, naming the macro and the line 
within it where the error occurred: 

**Error** filename (line) macroname(macroline) message 

The following warning and error messages are arranged in alphabetical 
order: 

Argument needs type override 

The expression needs to have a specific size or type supplied, since its 
size can't be determined from the context. For example, 

mov [bx],l 
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You can usually correct this error by using the PTR operator to set the 
size of the operand: 

mov WORD PTR[bx],l 

Argument to operation or instruction has illegal size 

An operation was attempted on something that could not support the 
required operation. For example, 

Q LABEL QWORD 

QNOT = not Q ; can't negate a qword 

Arithmetic overflow 

A loss of arithmetic precision occurred somewhere in the expression. For 
example, 

X = 20000h * 20000h /overflows 32 bits 

All calculations are performed using 32-bit arithmetic. 

ASSUME must be segment register 

You have used something other than a segment register in an ASSUME 
statement. For example, 

ASSUME ax: CODE 

You can only use segment registers with the ASSUME directive. 

Assuming segment is 32 bit 

You have started a segment using the SEGMENT directive after having 
enabled 80386 instructions, but you have not specified whether this is a 
16- or 32-bit segment with either the USE16 or USE32 keyword. 

In this case. Turbo Assembler presumes that you want a 32-bit segment. 
Since that type of code segment won't execute properly under DOS 
(without you taking special measures to ensure that the 80386 processor 
is executing instructions in a 32-bit segment), the warning is issued as 
USE32. 

You can remove this warning by explicitly specifying USE16 as an argu- 
ment to the SEGMENT directive. 

Bad keyword in SEGMENT statement 

One of the align /combine/use arguments to the SEGMENT directive is 
invalid. For example, 

DATA SEGMENT PAFA PUBLIC ;PAFA should be PARA 

Can't add relative quantities 

You have specified an expression that attempts to add together two 
addresses, which is a meaningless operation. For example. 
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ABC DB ? 

DEF = ABC + ABC ;error, can't add two relatives 

You can subtract two relative addresses, or you can add a constant to a 
relative address, as in: 

XYZ DB 5 DUP (0) 

XYZEND EQU $ 

XYZLEN = SYZEND - XYZ ; perfectly legal 

XYZ2 = XYZ + 2 ; legal also 

Can't address with currently ASSUMEd segment registers 

An expression contains a reference to a variable for which you have not 
specified the segment register needed to reach it. For example, 

DSEG SEGMENT 

ASSUME ds:DSEG 

mov si,MPTR ;no segment register to reach XSEG 
DSEG ENDS 
XSEG SEGMENT 
MPTR DW ? 
XSEG ENDS 

Can't convert to pointer 

Part of the expression could not be converted to a memory pointer, for 
example, by using the PTR operator, 

mov cl, [BYTE PTR al] ;can't make AL into pointer 

Can't emulate 8087 instruction 

The Turbo Assembler is set to generate emulated floating-point 
instructions, either via the /E command-line option or by using the 
EMUL directive, but the current instruction can't be emulated. For 
example, 

EMUL 

FNSAVE [WPTR] /can't emulate this 

The following instructions are not supported by floating-point 
emulators: FNSAVE, FNSTCW, FNSTENV, and FNSTSW. 

Can't make variable public 

The variable is already declared in such a way that it can't be made 
pubHc. For example, 

EXTRN ABC: NEAR 

PUBLIC ABC ; error, already EXTRN 

Can't override ES segment 

The current statement specifies an override that can't be used with that 
instruction. For example. 
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stos DS:BYTE PTR[di] 

Here, the STOS instruction can only use the ES register to access the 
destination address. 

Can't subtract dissimilar relative quantities 

An expression subtracts two addresses that can't be subtracted from 
each other, such as when they are each in a different segment: 



SEGl 


SEGMENT 


A: 




SEGl 


ENDS 


SEG2 


SEGMENT 


B: 




mov ax,B-A 


SEG2 


ENDS 



;illegal, A and B in different segments 

Can't use macro name in expression 

A macro name was encountered as part of an expression. For example, 

MyMac MACRO 
ENDM 
mov ax, MyMac ;wrong! 

Can't use this outside macro 

You have used a directive outside a macro definition that can only be 
used inside a macro definition. This includes directives like ENDM and 
EXITM. For example, 

DATA SEGMENT 

ENDM ; error, not inside macro 

Code or data emission to undeclared segment 

A statement that generated code or data is outside of any segment 
declared with the SEGMENT directive. For example, 

;First line of file 

inc bx /error, no segment 
END 

You can only emit code or data from within a segment. 

Constant assumed to mean immmediate constant 

This warning appears if you use an expression such as [0], which under 
MASM is interpreted as simply 0. For example, 

mov ax[0] ;means mov ax,0 NOT mov ax,DS:[0] 

Constant too large 

You have entered a constant value that is properly formatted, but is too 
large. For example, you can only use numbers larger than Offffh when 
you have enabled 80386 instructions with the .386 or .386P directive. 
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CS not correctly assumed 

A near CALL or JMP instruction can't have as its target an address in a 
different segment. For example, 

SEGl SEGMENT 
LABI LABEL NEAR 
SEGl ENDS 
SEG2 SEGMENT 

jmp LABI ; error, wrong segment 
SEG2 ENDS 

This error only occurs in MASM mode. Ideal mode correctly handles this 
situation. 

CS override in protected mode 

The current instruction requires a CS override, and you are assembling 
instructions for the 286 or 386 in protected mode (P286P or P386P 
directives). For example, 

P286P 

.CODE 

CVAL DW ? 

mov CVAL,1 /generates CS override 

The /P command-line option enables this warning. When running in 
protected mode, instructions with CS overrides won't work without you 
taking special measures. 

CS unreachable from current segment 

When defining a code label using colon (:), LABEL or PROC, the CS 
register is not assumed to either the current code segment or to a group 
that contains the current code segment. For example, 

PROGl SEGMENT 

ASSUME cs:PR0G2 
START: ;error, bad CS assume 

This error only occurs in MASM mode. Ideal mode correctly handles this 
situation. 

Declaration needs name 

You have used a directive that needs a symbol name, but none has been 
supplied. For example, 

PROC ; error, PROC needs a name 

ret 
ENDP 

You must always supply a name as part of a SEGMENT, PROC, or 
STRUC declaration. In MASM mode, the name precedes the directive; in 
Ideal mode, the name comes after the directive. 
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Directive ignored in Turbo Pascal model 

You have tried to use one of the directives that can't be used when 
writing an assembler module to interface with Turbo Pascal. Read about 
the .MODEL directive that specifies Turbo Pascal in Chapter 3. Refer to 
Chapter 7 of the User's Guide for information about interfacing to Turbo 
Pascal. 

Directive not allowed inside structure definition 

You have used a directive inside a STRUC definition block that can't be 
used there. For example, 

X STRUC 
MEMl DB ? 

ORG $+4 ;error, can't use ORG inside STRUC 
MEM2 DW ? 
ENDS 

Also, when declaring nested structures, you cannot give a name to any 
that are nested. For example, 

FOO STRUC 

F002 STRUC ;can't name inside 

ENDS 
ENDS 

If you want to use a named structure inside another structure, you must 
first define the structure and then use that structure name inside the 
second structure. 

Duplicate dummy argument: 

A macro defined with the MACRO directive has more than one dummy 
parameter with the same name. For example, 

XYZ MACRO A, A ; error, duplicate dummy name 
DB A 
ENDM 

Each dummy parameter in a macro definition must have a different 
name. 

ELSE or ENDIF without IF 

An ELSE or ENDIF directive has no matching IF directive to start a 
conditional assembly block. For example, 

BUF DB 10 DUP (?) 

ENDIF ; error, no matching IFxxx 

Expecting offset quantity 

An expression expected an operand that referred to an offset within a 
segment, but did not encounter the right sort of operand. For example. 
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CODE SEGMENT 

mov ax, LOW CODE 
CODE ENDS 

Expecting offset or pointer quantity 

An expression expected an operand that referred to an offset within a 
specific segment, but did not encounter the right sort of operand. For 
example, 

CODE SEGMENT 

mov ax,SEG CODE ;error, code is a segment not 
; a location within a segment 
CODE ENDS 

Expecting pointer t3^e 

The current instruction expected an operand that referenced memory. 
For example, 

les di,4 ;no good, 4 is a constant 

Expecting scalar type 

An instruction operand or operator expects a constant value. For 
example, 

BB DB 4 

rol ax,BB ;ROL needs constant 

Expecting segment or group quantity 

A statement required a segment or group name, but did not find one. 
For example, 

DATA SEGMENT 

ASSUME ds:FOO ;error, FOO is not a group or segment name 
FOO DW 
DATA ENDS 

Extra characters on line 

A valid expression was encountered, but there are still characters left on 
the line. For example, 

ABC = 4 shl 3 3 ;missing operator between 3 and 3 

This error often happens in conjimction with another error that caused 
the expression parser to lose track of what you intended to do. 

Forward reference needs override 

An expression containing a forward-referenced variable resulted in more 
code being required than Turbo Assembler anticipated. This can happen 
either when the variable is unexpectedly a far address for a JMP or 
CALL or when the variable requires a segment override in order to 
access it. For example. 
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ASSUME cs:DATA 

call A ; presume near call 

A PROC FAR ;oops, it's far 

mov ax,MEMVAR /doesn't know it needs override 
DATA SEGMENT 

MEMVAR DW ? ;oops, needs override 

Correct this by explicitly supplying the segment override or FAR 
override. 

ID not member of structure 

In Ideal mode, you have specified a symbol that is not a structure 
member name after the period (.) structure member operator. For 
example, 

IDEAL 
STRUC DEMO 

DB ? 
ENDS 
COUNT DW 

mov ax, [(DEMO bx) .COUNT] ;COUNT isn't part of structure 

You must follow the period with the name of a member that belongs to 
the structure name that precedes the period. 

This error often happens in conjunction with another error that caused 
the expression parser to lose track of what you intended to do. 

Illegal forward reference 

A symbol has been referred to that has not yet been defined, and a 
directive or operator requires that its argument not be forward- 
referenced. For example, 

IF MYSYM ; error, MYSYM not defined yet 

ENDIF 
MYSYM EQU 1 

Forward references may not be used in the argument to any of the IFxxx 
directives, nor as the count in a DUP expression. 

Illegal immediate 

An instruction has an immediate (constant) operand where one is not 
allowed. For example, 

mov 4,al 

Illegal indexing mode 

An instruction has an operand that specifies an illegal combination of 
registers. For example. 
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mov al, [si+ax] 

On all processors except the 80386, the only valid combinations of index 
registers are: BX, BP, SI, DI, BX+SI, BX+DI, BP+SI, BP+DI. 

Illegal instruction 

A source line starts with a symbol that is neither one of the known 
directives nor a valid instruction mnemonic. 

move ax, 4 /should be "MOV" 

Illegal instruction for currently selected processor(s) 

A source line specifies an instruction that can't be assembled for the 
current processor. For example, 

.8086 

push 1234h ;no immediate push on 8086 

When Turbo Assembler first starts assembling a source file, it generates 
instructions for the 8086 processor, unless told to do otherwise. 

If you wish to use the extended instruction mnemonics available on the 
186/286/386 processors, you must use one of the directives that enables 
those instructions (P186, P286, P386). 

Illegal local argument 

The LOCAL directive inside a macro definition has an argument that is 
not a valid symbol name. For example, 

X MACRO 

LOCAL 123 ;not a symbol 
ENDM 

Illegal local symbol prefix 

The argument to the LOCALS directive specifies an invalid start for 
local symbols. For example, 

LOCALS XYZ ; error, not 2 characters 

The local S5anbol prefix must be exactly two characters that themselves 
are a valid symbol name, such as , @@, and so on (the default is @@). 

Illegal macro argument 

A macro defined with the MACRO directive has a dummy argument 
that is not a valid symbol name. For example, 

X MACRO 123 /invalid dummy argument 
ENDM 

Illegal memory reference 

An instruction has an operand that refers to a memory location, but a 
memory location is not allowed for that operand. For example. 
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mov [bx],BYTE PTR A ; error, can't move from MEM to MEM 

Here, both operands refer to a memory location, which is not a legal 
form of the MOV instruction. On the 80x86 family of processors, only 
one of the operands to an instruction can refer to a memory location. 

Illegal number 

A number contains one or more characters that are not valid for that 
type of number. For example, 

Z = OABCGh 

Here, G is not a valid letter in a hexadecimal number. 

Illegal origin address 

You have entered an invalid address to set the current segment location 
($). You can enter either a constant or an expression using the location 
counter ($), or a symbol in the current segment. 

Illegal override in structure 

You have attempted to initialize a structure member that was defined 
using the DUP operator. You can only initialize structure members that 
were declared without DUP. 

Illegal override register 

A register other than a segment register (CS, DS, ES, SS, and on the 
80386, FS and GS) was used as a segment override, preceding the colon 
(:) operator. For example, 

mov dx:XYZ,l ;DX not a segment register 

Illegal radix 

The number supplied to the .RADIX directive that sets the default 
number radix is invalid. For example, 

.RADIX 7 ;no good 

The radix can only be set to one of 2, 8, 10, or 16. The number is 
interpreted as decimal no matter what the current default radix is. 

Illegal register multiplier 

You have attempted to multiply a register by a value, which is not a legal 
operation; for example, 

mov ax*3,l 

The only context where you can multiply a register by a constant expres- 
sion is when specifying a scaled index operand on the 80386 processor. 
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Illegal use of constant 

A constant appears as part of an expression where constants can't be 
used. For example, 

mov bx+4,5 

Illegal use of register 

A register name appeared in an expression where it can't be used. For 
example, 

X = 4 shl ax ;can't use register with SHL operator 

Illegal use of segment register 

A segment register name appears as part of an instruction or expression 
where segment registers cannot be used. For example, 

add SS,4 ;ADD can't use segment regs 

Illegal USES register 

You have entered an invalid register to push and pop as part of entering 
and leaving a procedure. The valid registers follow: 

AX CX DS ES 

BX DI DX SI 

If you have enable the 80386 processor with the .386 or .386P directive, 
you can use the 32-bit equivalents for these registers. 

Illegal warning ID 

You have entered an invalid three-character warning identifier. See the 
options discussed in Chapter 3 of the User's Guide for a complete list of 
the allowed warning identifiers. 

Instruction can be compacted with override 

The code generated contains NOP padding, due to some forward- 
referenced symbol. You can either remove the forward reference or 
explicitly provide the type information as part of the expression. For 
example, 

jmp X /warning here 
jmp SHORT X ;no warning 
X: 

Invalid model type 

The model directive has an invalid memory model keyword. For 
example, 

.MODEL GIGANTIC 

Valid memory models are tiny, small, compact, medium, large, and 
huge. 
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Invalid operand(s) to instruction 

The instruction has a combination of operands that are not permitted. 
For example, 

fadd ST (2), ST (3) 

Here, FADD can only refer to one stack register by name; the other must 
be the stack top. 

Labels can't start with numeric characters 

You have entered a symbol that is neither a valid number nor a valid 
symbol name, such as 123XyZ. 

Line too long - truncating 

The current line in the source file is longer than 255 characters. The 
excess characters will be ignored. 

Location counter overflow 

The current segment has filled up, and subsequent code or data will 
overwrite the beginning of the segment. For example, 

ORG OFFFOh 

ARRAY DW 20 DUP (0) /overflow 

Missing argument list 

An IRP or IRPC repeat block directive does not have an argument to 
substitute for the dummy parameter. For example, 

IRP X ;no argument list 

DB X 
ENDM 

IRP and IRPC must always have both a dummy parameter and an 
argument list. 

Missing argument or < 

You forgot the angle brackets or the entire expression in an expression 
that requires them. For example, 

ifb ; needs an argument in <>s 

Missing argument size variable 

An ARG or LOCAL directive does not have a symbol name following 
the optional = at the end of the statement. For example, 

ARG A:WORD,B:DWORD= ;error, no name after = 
LOCAL X:TBYTE= ;same error here 

ARG and LOCAL must always have a s)nnbol name if you have used 
the optional equal sign (=) to indicate that you want to define a size 
variable. 
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Missing COMM ID 

A COMM directive does not have a symbol name before the type 
specifier. For example, 

COMM NEAR /error, no symbol name before "NEAR" 

COMM must always have a symbol name before the type specifier, 
followed by a colon (:) and then the type specifier. 

Missing dummy argument 

An IRP or IRPC repeat block directive does not have a dummy 
parameter. For example, 

RP ;no dummy parameter 

DB X 
ENDM 

IRP and IRPC must always have both a dummy parameter and an 
argument list. 

Missing end quote 

A string or character constant did not end with a quote character. For 
example, 

DB "abc /missing " at end of ABC 
mov al,'X ;missing ' after X 

You should always end a character or string constant with a quote 
character matching the one that started it. 

Missing macro ID 

A macro defined with the MACRO directive has not been given a name. 
For example, 

MACRO ; error, no name 

DB A 
ENDM 

Macros must always be given a name when they are defined. 

Missing module name 

You have used the NAME directive but you haven't supplied a module 
name after the directive. Remember that the NAME directive only has 
an effect in Ideal mode. 

Missing or illegal language ID 

You have entered something other than one of the allowed language 
identifiers after the .MODEL directive. See Chapter 3 of this book for a 
complete description of the .MODEL directive. 
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Missing or illegal type specifier 

A statement that needed a type specifier (like BYTE, WORD, and so on) 
did not find one where expected. For example, 

RED LABEL XXX ; error, "XXX" is not a type specifier 

Missing term in list 

In Ideal mode, a directive that can accept multiple arguments (EXTRN, 
PUBLIC, and so on) separated by commas does not have an argument 
after one of the commas in the list. For example, 

EXTRN XXX:BYTE,,YYY:WORD 

In Ideal mode, all argtm:\ent lists must have their elements separated by 
precisely one comma, with no comma at the end of the list. 

Missing text macro 

You have not supplied a text macro argument to a directive that requires 
one. For example, 

NEWSTR. SUBSTR /ERROR - SUBSTR NEEDS ARGUMENTS 

Model must be specified first 

You used one of the simplified segmentation directives without first 
specifying a memory model. For example, 

.CODE ;error, no .MODEL first 

You must always specify a memory model using the .MODEL directive 
before using any of the other simplified segmentation directives. 

Name must come first 

You put a symbol name after a directive, and the symbol name should 
come first. For example, 

STRUG ABC ; error, ABC must come before STRUG 

Since Ideal mode expects the name to come after the directive, you will 
encounter this error if you try to assemble Ideal mode programs in 
MASM mode. 

Need address or register 

An instruction does not have a second operand supplied, even though 
there is a comma present to separate two operands; for example, 

mov ax, ;no second operand 

Need angle brackets for structure fill 

A statement that allocates storage for a structure does not specify an 
initializer Hst. For example. 
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STRl STRUC 
Ml DW ? 
M2 DD ? 

ENDS 

STRl ;no initializer list 

Need colon 

An EXTRN, GLOBAL, ARG, or LOCAL statement is missing the colon 
after the tj^ specifier (BYTE, WORD, and so on). For example, 

EXTRN X BYTE,y:WORD ;X has no colon 

Need expression 

An expression has an operator that is missing an operand. For example, 

X = 4 + * 6 

Need file name after INCLUDE 

An INCLUDE directive did not have a file name after it. For example, 

INCLUDE /include what? 

In Ideal mode, the file name must be enclosed in quotes. 

Need left parenthesis 

A left parenthesis was omitted that is required in the expression syntax. 
For example, 

DB 4 DUP 7 

You must always enclose the expression after the DUP operator in 
parentheses. 

Need pointer expression 

This error only occurs in Ideal mode and indicates that the expression 
between brackets ([ ]) does not evaluate to a memory pointer. For 
example, 

mov ax, [WORD PTR] 

In Ideal mode, you must always supply a memory-referencing expres- 
sion between the brackets. 

Need quoted string 

You have entered something other than a string of characters between 
quotes where it is required. In Ideal mode, several directives require 
their argument to be a quoted string. For example, 

IDEAL 

DISPLAY "ALL DONE" 
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Need register in expression 

You have entered an expression that does not contain a register name 
where one is required. 

Need right angle bracket 

An expression that initializes a structure, union, or record does not end 
with a > to match the < that started the initializer list. For example, 

MYSTRUC STRUCNAME <1,2,3 

Need right parenthesis 

An expression contains a left parenthesis, but no matching right paren- 
thesis. For example, 

X = 5 * (4 + 3 

You must always use left and right parentheses in matching pairs. 

Need right square bracket 

An expression that references a memory location does not end with a ] to 

match the [ that started the expression. For example, 

mov ax, [si /error, no closing ] after SI 

You must always use square brackets in matching pairs. 

Need stack argument 

A floating-point instruction does not have a second operand supplied, even 
though there is a comma present to separate two operands. For example, 

fadd ST, 

Need structure member name 

In Ideal mode, the period (.) structure member operator was followed by 
something that was not a structure member name. For example, 

IDEAL 
STRUC DEMO 

DB ? 
ENDS 
COUNT DW 

mov ax, [(DEMO bx) .] 

You must always follow the period operator with the name of a member in 
the structure to its left. 

Not expecting group or segment quantity 

You have used a group or segment name where it can't be used. For 
example. 
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CODE SEGMENT 

rol ax, CODE ;error, can't use segment name here 

One non-null field allowed per union expansion 

When initializing a union defined with the UNION directive, more than 
one value was supplied. For example, 

U UNION 

DW ? 

DD ? 
ENDS 
UINST U <1,2> ;error, should be <?,2> or <!,?> 

A union can only be initialized to one value. 

Open conditional 

The end of the source file has been reached as defined with the END 
directive, but a conditional assembly block started with one of the IFxxx 
directives has not been ended with the ENDIF directive. For example, 

IF BIGBUF 

END ;no ENDIF before END 

This usually happens when you type END instead of ENDIF to end a 
conditional block. 

Open procedure 

The end of the source file has been reached as defined with the END 
directive, but a procedure block started with the PROC directive has not 
been ended with the ENDP directive. For example, 

MYFUNC PROC 

END ;no ENDIF before ENDP 

This usually happens when you type END instead of END? to end a 
procedure block. 

Open segment 

The end of the source file has been reached as defined with the END 
directive, but a segment started with the SEGMENT directive has not been 
ended with the ENDS directive. For example, 

DATA SEGMENT 

END ;no ENDS before END 

This usually happens when you type END instead of ENDS to end a 
segment. 
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Open structure definition 

The end of the source file has been reached as defined with the END 
directive, but a structure started with the STRUC directive has not been 
ended with the ENDS directive. For example, 

X STRUC 
VALl DW ? 

END ;no ENDS before it 

This usually happens when you type END instead of ENDS to end a 
structiu-e definition. 

Operand types do not match 

The size of an instruction operand does not match either the other 
operand or one valid for the instruction; for example, 

ABC DB 5 



mov ax, ABC 

Pass-dependent construction encountered 

The statement may not behave as you expect, due to the one-pass nature 
of Turbo Assembler. For example, 

IFl 

;Happens on assembly pass 
ENDIF 
IF2 

/•Happens on listing pass 
ENDIF 

Most constructs that generate this error can be re-coded to avoid it, often 
by removing forward references. 

Pointer expression needs brackets 

In Ideal nnode, the operand contained a memory-referencing symbol that 
was not surrounded by brackets to indicate that it references a memory 
location. For example, 

B DB 

mov al,B /warning, Ideal mode needs [B] 

Since MASM mode does not require the brackets, this is only a warning. 

Positive count expected 

A DUP expression has a repeat count less than zero. For example, 

BUF -1 DUP (?) /error, count < 

The count preceding a DUP must always be 1 or greater. 
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Record field too large 

When you defined a record, the sum total of all the field widths 
exceeded 32 bits. For example, 

AREC RECORD RANGE: 12, TOP: 12, BOTTOM: 12 

Recursive definition not allowed for EQU 

An EQU definition contained the same name that you are defining 
within the definition itself. For example, 

ABC EQU TWOTIMES ABC 

Register must be AL or AX 

An instruction which requires one operand to be the AL or AX register 
has been given an invalid operand. For example, 

IN CL,dx /error, "IN" must be to AL or AX 

Register must be DX 

An instruction which requires one operand to be the DX register has 
been given an invalid operand. For example, 

IN AL,cx ; error, must be DX register instead of CX 

Relative jump out of range by bytes 

A conditional jump tried to reference an address that was greater than 
128 bytes before or 127 bytes after the current location. If this is in a 
USE32 segment, the conditional jump can reference between 32,768 
bytes before and 32,767 bytes after the current location. 

Relative quantity illegal 

An instruction or directive has an operand that refers to a memory 
address in a way that can't be known at assembly time, and this is not 
allowed. For example, 

DATA SEGMENT PUBLIC 
X DB 

IF OFFSET X GT 127 ;not known at assemble time 

Reserved word used as symbol 

You have created a symbol name in your program that Turbo Assembler 
reserves for its own use. Your program will assemble properly, but it is 
good practice not to use reserved words for your own symbol names. 

Rotate count must be constant or CL 

A shift or rotate instruction has been given an operand that is neither a 
constant nor the CL register. For example, 

rol ax,DL ; error, can't use DL as count 
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You can only use a constant value or the CL register as the second 
operand to a rotate or shift instruction. 

Rotate count out of range 

A shift or rotate instruction has been given a second operand that is too 
large. For example, 

.8086 

shl DL,3 ;error, 808S can only shift by 1 

.286 

ror ax, 40 ;error, max shift is 31 

The 8086 processor only allows a shift count of 1, but the other 
processors allow a shift count up to 31. 

Segment alignment not strict enough 

The align boimdary value supplied is invalid. Either it is not a power of 
2, or it specifies an alignment stricter than that of the align type in the 
SEGMENT directive. For example, 

DATA SEGMENT PARA 

ALIGN 32 ; error, PARA is only 16 
ALIGN 3 ; error, not power of 2 

Segment attributes illegally redefined 

A SEGMENT directive re-opens a segment that has been previously 
defined, and tries to give it different attributes. For example, 

DATA SEGMENT BYTE PUBLIC 

DATA ENDS 

DATA SEGMENT PARA /error, previously had byte alignment 

DATA ENDS 

If you re-open a segment, the attributes you supply must either match 
exactly or be omitted entirely. If you don't supply any attributes when 
re-opening a segment, the old attributes will be used. 

Segment name is superfluous 

This warning appears with a .CODE xxx statement, where the model 
specified doesn't allow more than code segment. 

String too long 

You have built a quoted string that is longer than the maximum allowed 
length of 255. 

Symbol already defined: 

The indicated sjnubol has previously been declared with the same type. 
For example, 

BB DB 1,2,3 

BB DB ? /error, BB already defined 
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Symbol already different kind 

The indicated symbol has already been declared before with a different 
type. For example, 

BB DB 1,2,3 

BB DW ? ; error, BB already a byte 

Symbol has no width or mask 

The operand of a WIDTH or MASK operator is not the name of a record 
or record field. For example, 

B DB 

mov ax, MASK B ;B is not a record field 

Symbol is not a segment or already part of a group 

The symbol has either already been placed in a group or it is not a 
segment name. For example, 

DATA SEGMENT 

DATA ENDS 

DGROUP GROUP DATA 

DGR0UP2 GROUP DATA /error, DATA already belongs to DGROUP 

Too few operands to instruction 

The instruction statement requires more operands than were supplied. 
For example, 

add ax ;missing second arg 

Too many errors or warnings 

No more error messages will be displayed. The maximum number of 
errors that will be displayed is 100; this number has been exceeded. 
Turbo Assembler continues to assemble and prints warnings rather than 
error messages. 

Too many initial values 

You have supplied too many values in a structure or union initialization. 
For example, 

XYZ STRUC 

Al DB ? 

A2 DD ? 

XYZ ENDS 

ANXYZ XYZ <1,2,3> ; error, only 2 members in XYZ 

You can supply fewer initializers than there are members in a structure 
or union, but never more. 

Too many register multipliers in expression 

An 80386 scaled index operand had a scale factor on more than one 
register. For example. 
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mov EAX, [2*EBX+4*EDX] ;too many scales 

Too many registers in expression 

The expression has more than one index and one base register. For 
example, 

mov ax, [BP+SI+DI] ;can't have SI and DI 

Too many USES registers 

You specified more than 8 USES registers for the current procedure. 

Trailing null value assumed 

A data statement like DB, DW, and so on, ends with a comma. TASM 
treats this as a null value. For example, 

db 'hello', 13, 10 ;same as ...,13,10? 

Undefined symbol 

The statement contains a symbol that wasn't defined anywhere in the 
source file. 

Unexpected end of file (no END directive) 

The source file does not have an END directive as its last statement. 

All source files must have an END statement. 

Unknown character 

The current source line contains a character that is not part of the set of 
characters that make up Turbo Assembler symbol names or expressions. 
For example, 

add ax, !1 ;error, exclamation is illegal character 

Unmatched ENDP: _ 

The ENDP directive has a name that does not match the PROC directive 
that opened the procedure block. For example, 

ABC PROC 

XYZ ENDP ; error, XYZ should be ABC 

Unmatched ENDS: _ 

The ENDS directive has a name that does not match either the 
SEGMENT directive that opened a segment or the STRUG or UNION 
directive that started a structure or union definition. For example, 

ABC STRUC 

XYZ ENDS /error, XYZ should be ABC 

DATA SEGMENT 

CODE ENDS /error, code should be DATA 
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USE32 not allowed without .386 

You have attempted to define a 32-bit segment, but you have not 
specified the 80386 processor first. You can only define 32-bit segments 
after you have used the .386 or .386P directives to set the processor to be 
80386. 

User-generated error 

An error has been forced by one of the directives, which then forces an 
error. For example, 

.ERR /shouldn't get here 

Value out of range 

The constant is a valid number, but it is too large to be used where it 
appears. For example, 

DB 400 



Fatal Error Messages 



Fatal error messages cause Turbo Assembler to immediately stop 
assembling your file. Whatever caused the error prohibited the assembler 
fi*om being able to continue. Here's a Hst of possible fatal error messages. 

Bad switch 

You have used an invalid command-line option. See Chapter 3 of the 
User's Guide for a description of the command-line options. 

Can't find ©file _ 

You have specified an indirect command file name that does not exist. 
Make sure that you supply the complete file name. Turbo Assembler 
does not presume any default extension for the file name. You've 
probably run out of space on the disk where you asked the cross- 
reference file to be written. 

Can't locate file 

You have specified a file name with the INCLUDE directive that can't be 
found. Read about the INCLUDE directive in Chapter 3 in this book to 
learn where Turbo Assembler searches for included files. 

An INCLUDE file could not be located. Make sure that the name 
contains any necessary disk letter or directory path. 

Error writing to listing file 

You've probably run out of space on the disk where you asked the listing 
file to be written. 
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Error writing to object file 

You've probably run out of space on the disk where you asked the object 
file to be written. 

File not found 

The source file name you specified on the command line does not exist. 
Make sure you typed the name correctly, and that you included any 
necessary drive or path information if the file is not in the current 
directory. 

File was changed or deleted while assembly in progress 

Another program, such as a pop-up utility, has changed or deleted the 
file after Turbo Assembler opened it. Turbo Assembler can't re-open a 
file that was previously opened successfully. 

Insufficient memory to process command line 

You have specified a command line that is either longer than 64K or can't 
be expanded in the available memory. Either simplify the command line 
or run Turbo Assembler with more memory free. 

Internal error 

This message should never happen during normal operation of Turbo 
Assembler. Save the file(s) that caused the error and report it to 
Borland's Technical Support department. 

Invalid command line 

The command line that you used to start Turbo Assembler is badly 
formed. For example, 

TASM ,MYFILE 

does not specify a source file to assemble. See Chapter 3 of the User's 
Guide for a complete description of the Turbo Assembler command line. 

Invalid number after 

You have specified a valid command-line switch (option), but have not 
supplied a valid numeric argument following the switch. See Chapter 3 
of the User's Guide for a discussion of the command-line options. 

Maximum macro expansion size exceeded 

A macro expanded into more text than would fit in the macro expansion 
area. Since this area is up to 64 Kb long, you will usually only see this 
message if you have a macro with a bug in it, causing it to expand in- 
definitely. 

Out of hash space 

The hash space has one entry for each symbol you define in your 
program. It starts out allowing 16,384 symbols to be defined, as long as 
Turbo Assembler is running with enough free memory. If your program 
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has more than this many symbols, use the /KH command-line option to 
set the number of symbol entries you need in the hash table. 

Out of memory 

You don't have enough free memory for Turbo Assembler to assemble 
your file. 

If you have any TSR (RAM-resident) programs installed, you can try 
removing them from memory and try assembling your file again. You 
may have to reboot your system in order for memory to be properly 
freed. 

Another solution is to split the source file into two or more source files, 
or rewrite portions of it so that it requires less memory to assemble. You 
can also use shorter symbol names, reduce the number of comments in 
macros, and reduce the number of forward references in your program. 

Out of string space 

You don't have enough free memory for symbol names, file names, 
forward-reference tracking information, and macro text. You can use the 
/KS command-line option to allocate more memory to the string space. 
Normally, half of the free memory is assigned for use as string space. 

Too many errors found 

Turbo Assembler has stopped assembling your file because it contained 
so many errors. You may have made a few errors that have snowballed. 
For example, failing to define a symbol that you use on many lines is 
really a single error (failing to define the symbol), but you will get an 
error message for each line that referred to the symbol. 

Turbo Assembler will stop assembling your file if it encounters a total of 
100 errors or warnings. 

Unexpected end of file (no END directive) 

Your source file ended without a line containing the END directive. All 
source files must end with an END directive. 
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80287 coprocessor 

.287 directive 54, 134 
80387 coprocessor 

.387 directive 55, 135 
.8086 directive 56 
.8087 directive 56 
80186 processor 

.186 directive 53, 133 
80286 processor 

.286 directive 53, 133, 134 

.286C directive 53 

.286P directive 54 
80386 processor 

.386 directive 54, 134 

.386C directive 55 

.386P directive 55, 134, 135 

arithmetic operations 13 

Ideal vs. MASM mode 179 
8087 coprocessor 

.8087 directive 56, 135 

emulating 127 
.186 directive 53 
.286 directive 53 
.287 directive 54 
.386 directive 54 
.387 directive 55 
8086 processor 

.8086 directive 56, 135 
<> (angle brackets) operator 

within macros 47 
.286C directive 53 
.386C directive 55 
[ ] operator 21 
.286P directive 54 
.386? directive 55 
+ (binary) operator 16 

- (binary) operator 17 
: (colon) directive 57 

: (colon) operator 19 
local symbols and 117 

- (hyphen), makefile prefix 194 
operator 15 

;; operator, within macros 49 
. (period) character 

Ideal vs. MASM mode 163 
. (period) operator 18 
+ (unary) operator 16 

- (unary) operator 18 



# character 189 

! character, MAKE utility 200 
\ character, makefile comments 189 
_ character. Turbo C and 122 
= directive 58 

Ideal vs. MASM mode 173 

* operator 16 
/ operator 19 
? operator 20 

! operator, within macros 48 
& operator, within macros 46 
% sign 

directives 52 

within macros 48 
©-sign 

local symbols and 117 

makefile prefix 194 

TLINK and 212 
/ml option, case sensitivity 5 



action symbols (TLIB) 223 
addition 

operator 16, 21 
alias values 5 
ALIGN directive 58 

Ideal vs. MASM mode 174 
.ALPHA directive 59 
AND operator 21 
angle brackets, within macros 47 
ARG directive 60 
BYTE type and 61 
Turbo Debugger and 60, 139 
arithmetic operations 13 

Ideal vs. MASM mode 174 
assembling 
conditional 80 
directives 103-109 
ENDIF directive 82 
error messages 85 
EXITM directive 96 
listing files 114 
MAKE utility and 183-209 
ASSUME directive 62 

B 

BASIC See Turbo Basic 
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Basic Input/Output System See BIOS 

%BIN directive 63 

bit fields, directive 143 

bit masks 30 

bitwise complement operator 32 

bitwise OR operator 33 

brackets operator 21 

BUILTINS.MAK 205 

BYTE operator 22 

BYTE type 

ARG directive and 61 
bytes, DB directive 72 

c 

C See Turbo C 

/C option, TUB 225 

/c option, TLINK 214 

case sensitive option, TLIB 225 

case sensitivity 

MAKE utiUty 206 

string comparisons 88, 89 

TCREF246 

TLIB 225 
CATSTR directive 64, 120 
characters 

displaying 133 

literal 47 

quoted 48 
©code symbol 6 
.CODE directive 64 
code segment 

directive 64 
code segment, directive 65 
CODESEG directive 65 
©CodeSize symbol 6 
colon directive 57 
colon operator 19 

local sjnnbols and 117 
Color Graphics Adapter See CG A 
COMM directive 65 
COMMAND.COM, MAKE utility and 

195 
command-line options 

MAKE utiUty 206 

TLINfK 213 
command-line syntax 

GREP227 



Ideal vs. MASM mode 177 

MAKE UtiUty 204 

OBJXREF234 

TLIB 221 
command lists (makefiles) 194 
COMMENT directive 66 
comments 66 

makefile 189 

suppressing 49 
comparisons 

case sensitivity and 88, 89 
compatibility with other assemblers 

59,171-176, See also UASU 

compatibility 
compiler options See individual 

listings 
conditional 

directives (MAKE) 201 

jumps See jtmips, conditional 
conditional assembly 

ELSE directive 80 

ENDIF directive 82 

error messages 85 

EXrrM directive 96 

false conditionals 125, 148 

IFl directive 103 

IF2 directive 104 

IFB directive 105 

IFDEF directive 105 

IFDIF directive 106 

IFE directive 106 

IFIDN directive 107 

IFNB directive 108 

IFNDEF directive 108 

listing files 114, 125, 148, 154 

macros 106, 107, 108 

screen display 133 
%CONDS directive 67 
.CONST directive 67 
CONST directive 68 
constants 

integer 143 

segments 
Ideal vs. MASM mode 179 
copying data See data, copying 
@Cpu symbol 7 
CREF126,160 
%CREF directive 68 
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.CREF directive 68 
%CREFALL directive 69 
%CREFREF directive 69 
%CREFUREF directive 70 
cross-reference 

disabling 126 

in listing files 68, 69, 126, 160 
unreferenced symbols 69 

TCREF utility 244-247 
cross-reference utility See TCREF 

utility. See OBJXREF utility 
CS register 

.CODE directive and 64 
%CTLS directive 70 
©curseg symbol 8 

D 

/D option, OBJXREF 237 
/d option, TLINK 215 
data 

allocating 20, 23, 28 

size 
DQ directive 77 
DT directive 78 
SIZE operator 38 

types 
UNKNOWN 43 

uninitialized 71 
.DATA? directive 71 
.DATA directive 71 
©data symbol 8 
data segment 

directives 67, 68, 71-72 

EVENDATA directive 95 

uninitialized 156 
data structures See structures 
DATAPTR operator 22 
DATASEG directive 72 
©DataSize symbol 9, 121 
date 9 

??date sjnnbol 9 
DB directive 72 
DD directive 73 

Turbo Debugger and 73 
debugging 60, 73, 75, 79, 116, 139 

map files and 213 
%DEPTH directive 74 



DF directive 75 

Turbo Debugger and 75 
directives 51-160, See also individual 

listings 

byte storage 72 

code segment 64, 65 

comments 66 

communal variables 65 

conditional assembly 80, 82, 

103-109, 114, 148, 154 

conditional jumps 112, 128 

coprocessor emulation 81 

cross-reference 68, 69, 126, 160 

current segment 132 

data segment 67, 68, 71-72, 95, 156 

data size 77, 78, 79 

disabling symbol table 131 

doubleword storage 73 

equate 58, 84 

error messages 85-94, 130, 132, 159 

even address 94, 95 

expressions 143 

external symbols 96 

false conditionals 125, 148 

far data 156 

global symbols 100 

Ideal mode 102 

Ideal vs. MASM mode 180 

include file listing 127 

include files 109 

integer constants 143 

labels 113 

linking libraries 110 

listing controls 126 

listing files 67-70, 74, 109, 114, 115, 

125, 128, 131, 135-137, 138, 142, 

145, 148, 152-155, 160 

local symbols 117, 128 

local variables 115 

macro expansion 96, 114, 119, 129, 

160 

macros 119, 141, 145 

MAKE utility 200 

MASM mode 120, 129, 142 

memory model 121, 124 

module names 125 

near data 57 

pointers 75, 77 
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procedures 83, 138 
processor 
control 133-135 
mode 53-57 
program terminatior\ 82 
public symbols 141 
pushmg/ popping registers 158 
quoted strings 76 
records 143 
repeating 111, 144 
segments 145, 156 
alignment 58, 94 
groups 101 
names 62 

ordering 59, 76, 148 
stack 60 

stack segment 149 
string 
concatenation 64 
definition 151 
position 110 
size 148 
structures/ unions 84, 149, 156 
suppressing floating-point 137 
symbols 87, 93, 94, 117 
table 153 
Disk Operating System See DOS 
DISPLAY directive 76 
displaying characters See characters, 

displaying 
division, operators 19, 31 
DOS 
date 9 

MAKE utility and 195 
segment ordering 76 
time 10 
DOS wildcards 

TUB utility 223 
DOSSEG directive 76 
doublewords 
DD directive 73 
DWORD operator 23 
DP directive 77 
DQ directive 77 
DT directive 78 
DUP operator 23 
DW directive 79 

Turbo Debugger and 79 



DWORD operator 23 



/e option, TLINK 215 
!elif directive 201 
ELSE directive 80 
!else directive 201 
ELSEIF directive 80 
EMUL directive 81 
END directive 82 
ENDIF directive 82 
lendif directive 201 
ENDM directive 83 
ENDP directive 83 
ENDS directive 84 
environment variables 

MASM mode 172 
EQ operator 24 
EQU directive 5, 84 

Ideal vs. MASM mode 173 

THIS operator and 41 
equal (=) directive 58 

Ideal vs. MASM mode 173 
equate directives 58, 84 

Ideal vs. MASM mode 84 
equate substitutions 5 
ERR directive 86 
.ERRl directive 86 
.ERR2 directive 86 
.ERR directive 85 
.ERRB directive 87 
.ERRDEF directive 87 
.ERRDIF directive 88 
.ERRDIFI directive 88 
.ERRE directive 89 
.ERRIDN directive 89 
.ERRIDNI directive 90 
EElRIFl directive 91 
ERRIF2 directive 91 
ERRIF directive 91 
ERRIFB directive 91 
ERRIFDEF directive 91 
ERRIFDIF directive 92 
ERRIFDIFI directive 92 
ERRIFE directive 92 
ERRIFIDN directive 92 
ERRIFIDNI directive 92 
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ERRIFNB directive 93 
ERRIFNDEF directive 93 
.ERRNB directive 93 
.ERRNDEF directive 94 
.ERRNZ directive 94 
lerror directive 204 
error messages 249-274 

conditional assembly 85 

directives 85-94, 130, 132, 159 

disabling 132 

fatal 272 

macros 93 

MAKE utiHty 204, 207 

multiple 124 

OBJXREF243 

symbols 87, 91-94 

TLINK 217 

warning 250 
errors, programming See also pitfalls 
EVEN directive 94 
EVENDATA directive 95 
exclamation mark, within macros 48 
.EXE files, TLINK 211 
EXITM directive 96 
explicit rules (makefiles) 189 
expressions 

byte size 22 

doubleword size 23 

evaluating 48 

far pointer size 25, 36 

integer constants 143 

operators in 13-45 

order of evaluation 14 

quadword size 36 

size of 34 

ten-byte size 40 

word size 45 
Extended Dictionary 215, 221 

creating 226 

flag, TUB 222 
external symbols See symbols, 

external 
EXTRN directive 96 

Ideal vs. MASM mode 97 

F 

far data 9, 10 



DF directive 75 

DP directive 77 

.FARDATA? directive 98 

FARDATA directive 99 

.FARDATA directive 98 

operator 24 

UFARDATA directive 156 
FAR operator 24 
7.FARDATA? directive 98 
©fardata? symbol 10 
FARDATA directive 99 
.FARDATA directive 98 
©fardata symbol 9 
fatal error messages 272 
file names 10 
??filename symbol 10 
©FileName symbol 10 
files 

assembly 10 

forcing compilation 206 

including (MAKE) 201 

listing See also listing files 

MAKE utility 183-209 

managing (MAKE) 183-209 

naming, TUB 223 

object 220-226 
OBJXREF utility 234-244 

output (OBJXREF) 237 

response 234 

response (OBJXREF) 236 

searches (GREP) 227-233 
floating-point 

emulation 127 
Ideal vs. MASM mode 179 

Ideal vs. MASM mode 172 

instructions 1 

suppressing assembly 137 
forward references 

FAR operator 24 
forward slash operator 19 
FWORD operator 25 

G 

GE operator 25 

general-purpose registers See also 

individual listings 
GLOBAL directive 100 



280 



Turbo Assembler Reference Guide 



Ideal vs. MASM mode 177 
global symbols 100 

cross-referencing 244-247 
greater than operators 25, 26 
GREP utility 227-233 

command-line syntax 227 

examples 231 

file specification 230 

operators 229 

search string 229 
GROUP directive 101 
grouping segments 8, 101 
GT operator 26 

H 

HIGH operator 26 

I 

/i option, TLINK 214 

IBM XT See IBM PC 

IDEAL directive 102 

Ideal mode 102 

expression grammar 166 
include files 110 
labels 113 

linking libraries 110 
local symbols 118 
MASM mode vs. 171-176 
operator precedence 14 
predefined symbols 5 
segment groups 102 

IFl directive 103 

IF2 directive 104 

IF directive 103 

!if directive 201 

IFB directive 105 

IFDEF directive 105 

IFDIF directive 106 

IFDIFI directive 106 

IFE directive 106 

IFIDN directive 107 

IFIDNI directive 107 

IFNB directive 108 

IFNDEF directive 108 

implicit rules (makefiles) 191 

%INCL directive 109 

linclude directive 201 



INCLUDE directive 109 
include files 

GLOBAL directive and 100 

Ideal mode 110 

listing 109, 127, 138 
INCLUDELIB directive 110 
inequality operator 31 
input/output See I/O 
INSTR directive 110, 120 
instruction mnemonics See 

mnemonics 
instruction set See also individual 

listings 
integers 

constants 143 
integers, constants 143 
I/O, screen 133 
IRP directive 111 
IRPC directive 111 



/JJUMPS option 113 

jumps 

conditional 112 
Ideal vs. MASM mode 178 
size of 128 
forward referenced 112 
Ideal vs. MASM mode 173 
Quirks mode 173 
SHORT operator and 37 
size of 112 

JUMPS directive 112 



/I option, TLINK 214 
LABEL directive 113 

Ideal mode 113 
labels 

defining 113 

PUBLIC directive and 113 
.LALL directive 114 
language syntax 161-169 
LARGE operator 27 
LE operator 28 
LENGTH operator 28 
less than operators 28, 30 
lexical grammar 161 
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.LFCOND directive 114 
libraries 

creating extended dictionaries 226 

including 110 

object module 220-226, 234-244 
linking See also TLINK utility 

high-level languages 121 

libraries 110 

Turbo Pascal 121 
%LINUM directive 114 
%LIST directive 115 
.LIST directive 115 
listing files 115 

%BIN directive 63 

conditional assembly 154 

conditional blocks 114 

control directives 67, 70, 126, 138, 

142, 180 

cross-reference information 68, 69, 

126, 160, 244-247 

directives 52, 74 

disabling 128, 160 

error messages 86 

false conditionals in 125, 148 

format 114, 125, 131, 135, 136, 137, 

152-155 

include files in 109, 127 

macro expansion 114, 119, 129 

suppressing macros 145 

titles 152, 154, 155 

tmreferenced symbols 69 
LCXZAL directive 115 

Turbo Debugger and 116 
local symbols 117 

disabling 128 

Ideal vs. MASM mode 118, 178 
local variables 115 
LOCALS directive 117 
logical operations 

AND 21 

Ideal vs. MASM mode 174 

NOT 32 

OR 33 

SHL37 

SHR38 

XOR45 
LOOP instruction 

Ideal vs. MASM mode 179 



LOW operator 29 
LT operator 30 

M 

/m option 

TLINK 213 
/m option, TLINK 211 
MACRO directive 119 
macros 

conditional assembly 107, 108 

conditional assembly directives 

106 

defining 119 

deleting 141 

error messages 88, 89, 90, 93 

expansion 
directives 129 
EXITM directive 96 
listing files 119, 160 
suppressing listing 145 

IRP directive and 111 

IRPC directive and 112 

listing 114, 138 

local variables 115 

MAKE utility 1% 

operators within 46-49 
%MACS directive 119 
MAKE utility 183-209 

aborting 205 

BUILTINS.M AKE file 205 

case sensitivity 206 

command-line options 206 

creating makefiles 188-204 

directives 200 

error messages 207 

example 184 

forcing compilation 206 

macros 196 

syntax 204 

TOUCH utility 206 
map files, TLINK 211, 213 
MASK operator 30 
MASM51 directive 120, 171 
MASM compatibility 171-176 

80386 processor 179 

ALIGN directive 174 

alternate directives 180 
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arithmetic operations 174 
BYTE operator 22 
command-line syntax 177 
conditional jumps 178 
constant segments 179 
directives 51, 120, 129 
DWORD operator 23 
enhancements 177-181 
environment variables 172 
equate directives 58, 173 
expression grammar 164 
FAR operator 24 
floating-point 

emulation 179 

format 172 
FWORD operator 25 
GLOBAL directive 177 
jumps 173 
listing controls 180 
local symbols 129, 178 
logical operations 174 
LOOP instruction (80386) 179 
NEAR operator 32 
operator precedence 14 
predefined 

symbols 5 

variables 180 
PROC operator 34 
Quirks mode 120, 142, 171, 172, 

175 
QWORD operator 36 
segment 

alignment 174 

groups 101 

ordering 59 

overrides 179 

registers 173 
shifts 181 

signed instructions 174 
TBYTE operator 40 
Turbo C and 122 
unions 178 

UNKNOWN operator 44 
variable redefinition 120 
version 5.1 120, 129, 171, 175 
?? version symbol 11 
MASM directive 120 



MASM mode See MASM 

compatibility 
math coprocessor See numeric 

coprocessor 
memory 

models 
directives 121, 124 
pointers 6, 9, 22 
Turbo Pascal 121 

operands 21 
Microsoft Assembler See MASM 

compatibility 
MOD operator 31 
MODEL directive 124 
.MODEL directive 121 

RETURNS keyword and 62, 140 
modular programming 

code segment 64 

combine types 146 

COMM directive and 65 

cross-referencing 244-247 

EXTRN directive 96 

module names 125 

PUBLIC directive 141 
modulus operator 31 
moving data See data, moving 
MS-DOS See DOS 
MULTERRS directive 124 
multiplication, operator 16 

N 

/N option, OBJXREF 238 
/n option, TLINK 214 
NAME directive 125 
NE operator 31 
near data 8 

: directive 57 

operator 32 
NEAR operator 32 
%NEWPAGE directive 125 
%NOCONDS directive 125 
%NOCREF directive 126 
%NOCTLS directive 126 
NOEMUL directive 127 
%NOINCL directive 127 
NOJUMPS directive 128 
%NOLIST directive 128 
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NOLOCALS directive 128 

%NOMACS directive 129 

NOMASM51 directive 129 

NOMULTERRS directive 130 

%NOSYMS directive 131 

NOT operator 32 

NOTHING keyword 63 

%NOTOC directive 51 

%NOTRUNC directive 131 

NOWARN directive 132 

numeric coprocessor 
emulating 81, 127 
suppressing assembly 137 

o 

/O option, OBJXREF 237 
object See object files 
object files 

cross referencing 234-244 

libraries 220-226 

module name 125 
object modules 

cross-referencer (OBJXREF) 
warnings 244 

cross-referencing 244 

OBJXREF 244 

OBJXREF utility 234-244 

TUB 220 
OBJXREF utility 234-244 

changing directories 237 

command-line options 235 

/D option 237 

error messages 243 

examples 238 

/N option 238 

reports 235, 239 

syntax 234 
OFFSET operator 33 
offsets 

size operator 27 

SMALL operator 39 
operands 

memory 21 

THIS operator 41 
operators 13-49, See also individual 

listings 

addition 16, 21 



allocated data 28 

comments 49 

data size 38 

division 19, 31 

equality 24 

expression evaluate 48 

expression size 23, 25, 34, 36, 40, 45 

greater than 25, 26 

GREP 229 

Ideal vs. MASM mode 21 

inequality 31 

less than 28, 30 

literal text string 47 

logical 21, 32, 33, 37, 38, 45 

macros 46-49 

modulus 31 

multiplication 16 

offset size 27, 39 

order of precedence 14, 15 

pointers 34, 37 

quoted character 48 

records 44 

repeating 23 

segment address 36 

substitute 46 

subtraction 17 

symbol 40, 41, 42 
options, command line See 

command-line options 
OR operator 33 
ORG directive 132 
%OUT directive 133 
overlays, TLINK utility 216 



P8086 directive 135 
P8087 directive 135 
P186 directive 133 
P286 directive 133 
P287 directive 134 
P386 directive 134 
P387 directive 135 
P286N directive 134 
P386N directive 134 
P286P directive 134 
P386P directive 135 
PAGE directive 135 
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%PAGESIZE directive 136 
parentheses operator 15 
Pascal See Turbo Pascal 
PC-DOS See DOS 
%PCNT directive 137 
percent sign 

directives 52 

within macros 48 
period 

Ideal vs. MASM mode 163 

operator 
Ideal mode 18 
pipes 195 

PN087 directive 137 
pointers 

48-bit 75, 77 

DATAPTR operator 22 

DF directive 75 

PROC operator 34 
%POPLCTL directive 138 
precedence (operators) 14, 15 
predefined symbols See symbols 
prefixes, makefiles 194 
PROC directive 138 

RETURNS keyword 62, 140 
PROC operator 34 
procedures 

ending 83 

local variables 115 

start of 138 
processor control directives 133-135 
processor type, determining 7 
program management (MAKE) 

183-209 
program termination 

END directive and 82 
Prolog See Turbo Prolog 
PTR operator 34 
PUBLIC directive 141 
public names 

OBJXREF utUity 234, 239 
public symbols 141 
PURGE directive 141 
%PUSHLCTL directive 142 
PWORD operator 36 



Q 

quadwords 

DQ directive 77 

operator 36 
question mark 

operator 20 

symbols using 6 
QUIRKS directive 120, 142, 171, 175 
QUIRKS mode 120 
Quirks mode 172, 175 
QWORD operator 36 

R 

RADIX directive 143 
.RADIX directive 143 
RECORD directive 143 
records 

bit fields 143 

bit masks 30 

WIDTH operator 44 
redirection 195 

registers See also individual listings 
repeating instructions 23, 111, 144 
reports (OBJXREF) 

by class type 235 
REPT directive 144 
response files 

OBJXREF 234, 236 

TCREF245 

TUB 224 

TLINK211 
RETURNS keyword 62, 140 
rules (makefiles) 189-194 

s 

/S option 148 
/s option 

TLINK 211, 213 
.SALL directive 145 
searches (GREP) 227-233 
SEG operator 36 
SEGMENT directive 145 
segments 

address operator 36 

alignment 
Ideal vs. MASM mode 174 
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types 145 
alphabetical order 59 
ASSUME directive 62 
combine types 146 
constant 

Ideal vs. MASM mode 179 
current 8, 132 
data 156 
defining 145 
directives 145 
memory model 121, 124 
OFFSET operator 33 
simplified (>, 8, 9, 10 
end of 84 
groups 8, 101 

Ideal mode 101 
names 62 

NOTHING keyword 63 
OFFSET operator 33 
ordering 76, 148 
override 19 

Ideal vs. MASM mode 179 
registers See also individual 
listings 

Ideal vs. MASM mode 173 
Quirks mode 173 
sequential order 148 
size 11 
stack 149 
semicolon, within macros 49 
.SEQ directive 148 
.SECOND directive 148 
shifts 

Ideal vs. MASM mode 181 
SHL operator 37 
SHR operator 38 
SHL operator 37 
SHORT operator 37 
SHR operator 38 
sign, changing 18 
signed instructions 

Ideal vs. MASM mode 174 
simplified segment directives 6, 8, 9, 
10 

memory model 121, 124 
size of data See data, size 
SIZE operator 38 
SIZESTR directive 120, 148 



slash, operator 19 
SMALL operator 39 
square brackets, operator 21 
stack 

ARC directive 60 
STACK directive 149 
stack segment directive 149 
.STACK directive 149 
strings 

concatenating 64 

defining 64, 151 

directives 151 

DISPLAY directive 76 

displaying 76 

literal 47 

position 110 

quoted 48 

size 148 
STRUC directive 149 

Ideal vs. MASM mode 150 

vs. UNION 156 
structures 

defining 149 

directive 149 

ENDS directive 84 

LABEL directive and 113 

nesting 151 

period operator 18 
SUBSTR directive 120, 151 
subtraction 

Ideal vs. MASM mode 17 

operator 17 
SUBTTL directive 152 
%SUBTTL directive 152 
symbol tables 

listing files 153 
suppressing 131 
symbols 5-11 

aliases 5 

©code 6 

©CodeSize 6 

communal 65 
Ideal vs. MASM mode 66 
multiple 66 

©Cpu7 

cross-referencing 69 

©curseg 8 

©data 8 
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©DataSize 9 

??date 9 

defining 113 

error messages 87, 91, 93, 94 

external, EXTRN directive 96 

©fardata? 10 

©fardata 9 

??filename 10 

©FileName 10 

global 100 
cross-referencing 244-247 

local 117 
disabling 128 

operators 42 

public 141 

SYMTYPE operator 40 

??time 10 

.TYPE operator 41 

undefined 94 

unreferenced 69 

?? version 11 

©WoniSize 11 
%SYMS directive 153 
SYMTYPE operator 40 
syntax 161-169 

command-line See command-line 

syntax 

lexical grammar 161 



/t option, TLINK 216 
%TABSIZE directive 153 
TASM 

summary, operating modes 175 
TBYTE operator 40 
TCREFutiUty 244-247 

command-line options 245 

output 246 

TLINK and 245 
termination 

END directive and 82 
text strings See strings 
%TEXT directive 154 
.TFCOND directive 154 
THIS operator 41 
/3 option, TLINK 216 
time 10 



??time symbol 10 
TITLE directive 154 
%TITLE directive 155 
TLIB utiUty 220-226 

examples 226 

Extended Dictionary 221 
flag 222 

file names 223 

operation list 222 

operations 223 

response files 224 

syntax 221 
TLINK utility 210-220 

command-line options 213 

error messages 217 

Extended Dictionary 215 

generating .COM files 216 

map files 211, 213 

response files 211 

restrictions 216 

segment map 213 

TCREFand245 
%TOC directive 51 
TOUCH utiUty 206 
TPASCAL memory model 121 
%TRUNC directive 155 
Turbo C, linking to 122 
Turbo Debugger 

ARC directive and 60, 139 

DD directive and 73 

DF directive and 75 

DW directive and 79 

LOCAL directive and 116 
Turbo Librarian See TLIB utility 
Turbo Link See TLINK utility 
Turbo Pascal 

ARG directive and 62 

linking to 121 

.MODEL directive 121 

PROC directive and 140 
Turbo Prolog, linking to 122 
two-pass assemblers 

compatibility with 86, 104 
TYPE operator 42 
.TYPE operator 41 
typefaces in this manual 2 
types See data, types 
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u 

UDATASEG directive 156 
UFARDATA directive 156 
unconditional jumps See jumps, 

unconditional 
lundef directive 204 
underscore 

local symbols and 117 

Turbo C and 122 
UNION directive 150, 156 

vs. STRUG 156 
unions 

directive 156 

Ideal vs. MASM mode 178 
UNKNOWN operator 43 
USES directive 158 
utilities 183-247 

GREP 227-233 

MAKE 183-209 

OBJXREF 234-244 

TCREF 244-247 

TLIB 220-226 

TLINK 210-220 



local 115 

predefined 
Ideal vs. MASM mode 180 

redefining 120 
??version symbol 11 
version number (Turbo Assembler) 

11 

w 

WARN directive 159 
warning messages 250 

directives 159 

disabling 132 

TLINK 217 
WIDTH operator 44 
wildcards See DOS wildcards 
WORD operator 45 
words 

DW directive 79 

WORD operator 45 
©WordSize symbol 11 



V 

/v option, TLINK 216 
variables 

communal 65 

global (OBJXREF utility) 234 



/x option, TLINK 211 
JCALL directive 160 
JCCREF directive 160 
.XLIST directive 160 
XOR operator 45 
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